Una venta de punta a punta

En este tutorial sigues una sola venta por todo el Merchant: la cobras, la ves entrar al lote, se compensa, se liquida, se concilia y, al final, la cobras a distancia en el terminal de un repartidor. Son siete lecciones de unos cinco minutos. Cada una tiene una idea, lo que pasa por dentro y algo para probar.

Antes de empezar

• Los ejemplos van contra un ambiente de pruebas con banco simulado. No se mueve dinero real.
• Necesitas la dirección de tu servidor Merchant de pruebas y una clave de API de integración de tu comercio de pruebas. Las dos te las da quien administra tu ambiente; en los ejemplos aparecen como <TU_SERVIDOR_MERCHANT> y <TU_CLAVE_API>.
• Nunca pongas una clave de API en un navegador ni en un equipo del mostrador: se usa desde un servidor.
• El código de comercio de los ejemplos (<TU_CODIGO_COMERCIO>) es el de tu comercio de pruebas.

Lección 1. La compra con tarjeta

La idea. Pagar con tarjeta es pedir permiso por teléfono. El terminal no sabe si el cliente tiene dinero: llama al banco emisor y espera un «sí» o un «no» con su motivo. El Merchant es la centralita y el switch Aurora es la línea.

Por dentro.

1. La caja le dice al terminal el monto. El número de la tarjeta y la clave nunca pasan por la caja.
2. El terminal envía la compra al Merchant con su propia credencial. El Merchant comprueba el terminal y reconoce la marca por el rango de la tarjeta.
3. El Merchant arma un mensaje ISO 8583 de compra (tipo 0200) y lo envía al switch.
4. El switch lo enruta por el BIN al emisor, que responde (tipo 0210) con un código de respuesta.
5. Con 00 hay código de autorización y referencia (RRN), y la venta se captura en el lote abierto. Con cualquier otro código queda registrada, pero fuera del lote.

Para pensar. ¿Quién aprueba? El emisor, no FINORA. ¿Una respuesta 00 sin referencia es una aprobación? No: es un error de contrato.

Lección 2. Pago móvil y los otros rieles

La idea. Un peaje con varios carriles: la venta es el carro y el medio de pago es el carril. Lo explica a fondo Intención, intento y veredicto.

Por dentro. La caja abre una intención y el Merchant le responde qué medios acepta el comercio y qué datos pide cada uno. Luego la caja abre un intento por un medio concreto. Si el intento se aprueba y cubre el monto, la intención queda PAGADA.

Pruébalo. Crea la intención:

curl -s -X POST "<TU_SERVIDOR_MERCHANT>/api/v1/pagos/intenciones" \
  -H "X-API-Key: <TU_CLAVE_API>" -H "Content-Type: application/json" \
  -d '{"idempotencyKey":"venta-0042","merchantCode":"<TU_CODIGO_COMERCIO>",
       "amount":150.00,"currency":"VES","description":"Venta 0042"}'

La respuesta trae la referencia de la intención (<REFERENCIA>) y los medios disponibles. Abre un intento de pago móvil con datos de prueba:

curl -s -X POST "<TU_SERVIDOR_MERCHANT>/api/v1/pagos/intenciones/<REFERENCIA>/intentos" \
  -H "X-API-Key: <TU_CLAVE_API>" -H "Content-Type: application/json" \
  -d '{"railCode":"PAGO_MOVIL","amount":150.00,
       "datosPagador":{"cedula":"V00000001","telefono":"04140000000","banco":"<CODIGO_BANCO>"}}'

Repite la primera llamada con la misma idempotencyKey: recibes la misma intención, no una nueva.

Con el banco simulado. Los céntimos del monto eligen el desenlace: un monto terminado en ,51 se rechaza con 51 (fondos insuficientes), y uno terminado en ,96 se aprueba con retraso, a propósito, para que veas el EN_DUDA y cómo el barrido lo confirma después. Las reglas exactas del simulador te las da tu ambiente.

Para pensar. Si el pago móvil se rechaza, ¿se puede cobrar la misma venta con tarjeta? Sí: es otro intento de la misma intención. Si se venció el tiempo de espera, ¿se reintenta con una clave nueva? Nunca: eso sería cobrar dos veces.

Lección 3. El lote y por qué se cierra

La idea. La caja de zapatos con los comprobantes del día: al cerrar se cuentan, se suman y se comparan con la máquina.

Por dentro. Hay un lote abierto por terminal; se abre con la primera venta aprobada y solo acumula aprobadas. Al cerrar, el terminal declara sus totales:

{ "terminalId": "<TU_TID>", "numeroLote": 1,
  "totales": { "cantidadVentas": 2, "totalVentas": 21230,
               "cantidadDevoluciones": 0, "totalDevoluciones": 0 } }

Los montos van en céntimos: 21230 son Bs 212,30. Si los totales coinciden con lo que tiene el Merchant, el lote queda cerrado; si no, queda rechazado y visible para revisión.

Para pensar. ¿Por qué el terminal manda sus propios totales si el Merchant ya los conoce? Porque son dos verdades independientes y el cierre las confronta. Lo amplía El ciclo del lote.

Lección 4. La compensación: contarle a la marca lo que pasó

La idea. El reporte del vendedor a la oficina central: es información, no dinero; pero sin reporte no hay pago.

Por dentro. Son elegibles las ventas aprobadas, capturadas, de un lote cerrado y que no se hayan presentado antes. Se agrupan por marca y por ciclo, y se genera un archivo por marca. Cada registro recibe su ARN.

Para pensar. Si la corrida se repite para la misma marca, fecha y ciclo, no se duplica nada: es idempotente. Una compra de un lote que sigue abierto no entra.

Note

Los archivos que genera hoy el Merchant tienen el formato lógico de cada marca. La transmisión física a una marca forma parte de una certificación que todavía no se ha hecho.

Lección 5. La liquidación: cuándo y cuánto cobra el comercio

La idea. Como una nómina: el bruto menos las deducciones, en una fecha fija.

Por dentro. Cada comercio tiene su regla de liquidación: comisión (MDR) en puntos básicos, interchange y plazo (T+n). Se aplican también las retenciones de ISLR, IVA e IGTF que correspondan.

El ejemplo con números. Bs 125,00 + Bs 87,30 = Bs 212,30 de bruto. Con MDR de 250 puntos básicos (2,5 %), la comisión es Bs 5,31 y el neto es Bs 206,99, con fecha valor T+1.

Para pensar. Si cambias la comisión a 180 puntos básicos, ¿cambia la liquidación de ayer? No: una liquidación ya calculada no se recalcula. El cambio vale para las fechas nuevas (212,30 − 3,82 = 208,48).

Lección 6. La conciliación: cuadrar tres verdades

La idea. Una balanza de tres platos: lo cobrado, lo compensado y lo que dice el procesador.

Por dentro. Se concilia por archivo, por compensación, por liquidación y por transacción. Cuando algo no cuadra aparece una excepción: capturada y no compensada, compensada y no capturada, coincidencia duplicada o diferencia de monto. Lo detalla La conciliación en cuatro niveles.

Para pensar. Una venta capturada que no aparece en ningún archivo, ¿qué suele ser? Un lote que no se cerró. ¿Por qué la búsqueda se acota al día? Porque el STAN y el RRN se repiten con el tiempo.

Lección 7. El cobro empujado: el repartidor cobra sin tocar la caja

La idea. La comanda que la cocina imprime en el mostrador del mesero: el pedido aparece donde tiene que aparecer.

Por dentro. El sistema del comercio crea la intención con un bloque despacho que indica el terminal del repartidor. El terminal, que está escuchando al Merchant, recibe la orden, abre solo la pantalla de cobro, el cliente paga con su tarjeta y el terminal reporta el resultado. Si nadie la atiende en cinco minutos, la orden vence.

curl -s -X POST "<TU_SERVIDOR_MERCHANT>/api/v1/pagos/intenciones" \
  -H "X-API-Key: <TU_CLAVE_API>" -H "Content-Type: application/json" \
  -d '{"idempotencyKey":"pedido-1","merchantCode":"<TU_CODIGO_COMERCIO>","amount":24.99,
       "currency":"VES","description":"Pedido a domicilio",
       "despacho":{"terminalId":"<TID_DEL_REPARTIDOR>","ttlSegundos":300}}'

Para pensar. Si envías una segunda venta al mismo terminal antes de que resuelva la primera, el Merchant responde 409 TERMINAL_OCUPADO: un terminal cobra una cosa a la vez. Vencer no es rechazar: la intención sigue ahí y se puede volver a despachar. Lo explica Cobro empujado.

Lo que lograste

Seguiste una venta por todo su ciclo: autorización, lote, compensación, liquidación y conciliación, y la cobraste a distancia. Para el vocabulario, consulta el glosario del Merchant.

Si vas a integrar un punto de venta, sigue por el que te toca: una caja de terceros con FINORA Pago, una tienda web con FINORA Checkout, o la caja de FINORA con tu primera venta en FINORA Caja.