Solo kiosco Android. POS, web e iOS no usan este paquete.
Los paquetes son públicos en el SDK
0.12.5. Entran a npm en el próximo release. Un canal de este repositorio los depende con workspace:*.
Sigue las secciones de abajo para integrarlo a mano. Para dárselo a un agente, copia el prompt de Prompt para un agente.
Requisitos
- Un kiosco Android con development build. Expo Go no carga el módulo nativo.
- Un pinpad Medianet en la LAN del local.
CajaPinPadLibrary_V3.jar(WPOSS), fuera de git. Medianet licencia el JAR.
Activarlo
- En el dashboard, abre el comercio, entra a Payments y crea un pago con el proveedor Medianet y el método PIN pad. El nombre del pago es el texto del botón del checkout. Ver Botón del checkout.
- En Connection Settings, completa:
- En Store settings, completa cada tienda que necesite otro MID. Vacío significa el MID del pago. La API le entrega al kiosco solo la fila de su tienda.
- En cada kiosco, abre el dispositivo y la pestaña Payments. Los valores viven en
settings_overrides.payment_settings, con el id del pago como clave. Ver Configurar un dispositivo.
El MID se resuelve así: dispositivo, luego tienda, luego pago.
Un pago al que le falta
terminal_ip, terminal_port, terminal_id, cashier_id o un MID no llega al kiosco, así que su botón no aparece en el checkout. En el listado de dispositivos, la columna Payments muestra lo que sigue vacío. Un dispositivo también puede ocultar un pago con disabled_payment_ids.Botón del checkout
Cada pago Medianet es un botón. El template del kiosco ya pinta una tarjeta por pago a partir deservices.payments.list (CheckoutPaymentMethodCard). No agregas un componente de botón ni una ilustración.
- El texto es
payment.name. Si el pago no tiene nombre, la tarjeta usa el nombre del método. - La imagen es la ilustración de tarjeta.
paymentInstructionKinddevuelve"card"para todo pagoPIN_PAD, y el texto debajo escheckout.method.cardHint(“Débito o crédito en el datáfono”). Medianet no tienemodalities, así que la tarjeta nunca se trata como Pix y el cliente no elige débito o crédito en el kiosco. Eso lo hace el pinpad. - Débito y crédito son el mismo botón. Un segundo pago Medianet es una segunda tarjeta, con su nombre y sus datos de dispositivo.
Usarlo en el SDK
Agrega los dos paquetes a la app del kiosco. No forman parte del template público. Fíjalos a la misma versión que@fire-spark/payments.
@fire-spark/payments-medianet-client es el módulo Android y el config plugin de Expo. @fire-spark/payments-medianet-pinpad-rn es el adaptador. Cobra con el adaptador. No abras un socket ni armes tramas.
En app.config.ts:
binariesDir es absoluta o relativa a la raíz de la app. Apúntala a una carpeta fuera de git:
android/app/libs/, lo agrega al build.gradle de la app y pide el permiso de internet. El prebuild se detiene con [medianet] missing ... si falta el JAR. medianet.available, de @fire-spark/payments-medianet-client, es true cuando el plugin está en el build.
Regístralo una vez por pedido, con el almacenamiento del dispositivo. Pasa storage siempre: ahí queda el lote del día (medianet:control:v1) y la cola de reversos. Sin él, el pinpad puede volver a pedir la apertura del lote y se pierde un reverso pendiente. El adaptador ya usa el cliente compartido. No crees otro.
kioskConfig es lo que devuelve getKioskConfig. Los valores del dispositivo llegan en overrides.payment_settings. Las fechas de la trama usan America/Guayaquil, salvo que pases timeZone.
order.getMissingPaymentFields(payment) lista los campos del dispositivo que siguen vacíos. La API ya oculta un pago incompleto. Usa el helper en la pantalla de administración del kiosco cuando quieras mostrar lo que falta.
Aviso de espera
El adaptador no dibuja nada. Manda una sola línea, en español, mientras el pinpad trabaja:message. No hay select, input, confirm ni QR. Implementa message solo cuando esa línea deba verse en el kiosco:
Cobrar
Cobra el pago que eligió el cliente:payIntent({ payment }) igual coloca un tender. Para partir Medianet con otro método, llama a setTenders con una asignación y después a payIntent(). Ver Usar pagos en el SDK.
El primer cobro del día manda la trama de apertura del lote (PC) una sola vez. Si esa trama falla, no hay cobro. Una venta se aprueba solo cuando el pinpad y el autorizador responden 00. El monto va en centavos; el adaptador lo arma.
El plazo del cobro es de 300 segundos. Cubre el PC del día, la venta y un reverso. Deja runtime.timeout_ms sin definir para conservar ese plazo. Un valor en el pago lo reemplaza, así que pon 300000 o más. Para subir el valor por defecto del adaptador, pasa timeoutMs:
formatPaymentError de @fire-spark/payments. No reintentes un resultado AMBIGUOUS.
Qué ve el cliente
El botón de tarjeta y después el pinpad. El kiosco no dibuja una pantalla de pinpad ni muestra un QR. ConPAID, sigue el pedido. El código de autorización, la marca, los últimos 4, el secuencial (reference), el lote, el id de terminal y el id de comercio están en result.metadata.payment. El kiosco no los guarda por su cuenta.
Inicio del turno y configuración del pinpad
Llama a esto desde la pantalla de administración, nunca durante un cobro. El adaptador las corre de a una. Al abrir el turno, abre el lote del día. MandaPC aunque el día ya esté abierto. start también manda PC una vez por día si el turno no lo hizo:
Medianet batch <batch> open.
Escribe la red del pinpad (IP, máscara, gateway, puerto) solo cuando se guardan esos valores. Manda CP y después PC, y exige network_mask y gateway:
Medianet pinpad configured. Si faltan la máscara o el gateway, lanza Medianet is missing network_mask, gateway. El cobro no necesita esos dos campos.
Prueba de enlace, salud del módulo nativo y reversos pendientes:
test responde Medianet link OK (hash valid) o Medianet link OK (hash invalid). retry_pending_reversals responde Reverses and voids completed: N, pending: M.
No hay cierre de lote del pinpad. El cierre del día queda en el sistema de la tienda. No hay consulta de la última transacción. No armes las tramas.
Webhooks
Ninguno.Anulaciones
order.cancel() anula un pedido que no se entregó. order.refund() reembolsa uno que sí. Una venta aprobada se anula en el pinpad (03). Un resultado desconocido se reversa (04). Una anulación es REFUNDED solo cuando el pinpad y el autorizador responden 00.
Errores comunes
Compatibilidad
Prompt para un agente
Pega esto en el agente que edita la app del kiosco. Cubre solo Medianet. Las secciones de arriba son el mismo trabajo, escrito para una persona.Prompt de integración