Vietnam: VietQR, NAPAS 247 y MoMo operan en niveles distintos del pago

Imaginemos una caja con dos botones: VietQR y MoMo. En el primer caso, el comprador escanea los datos bancarios y transfiere el dinero. En el segundo, abre un flujo de pago acordado de MoMo. Ambos pagos pueden parecer igual de rápidos, pero dejan identificadores distintos y requieren confirmaciones distintas. Unirlos en un mismo registro interno es posible; declarar iguales sus estados externos, no.

Es especialmente importante no considerar VietQR y NAPAS 247 como dos pagos independientes y sucesivos. En el producto concreto NAPAS FastFund 247 a través de VietQR, el código sirve como forma cómoda de dirigir esa misma transferencia bancaria. A continuación, este esquema se separa de la API comercial de MoMo. Hablamos de la aceptación legal de ingresos, no de un permiso para que cualquier industria use los rieles locales.

Una compra por VietQR: qué conviene verificar

NAPAS describe la transferencia entre cuentas de bancos participantes mediante el escaneo de VietQR, las 24 horas, con un monto por operación inferior a 500 millones de VND. Es la descripción de ese producto de transferencia, no de cualquier pago QR en Vietnam. El código simplifica la carga de los datos bancarios, pero no demuestra que el beneficiario sea un comercio aprobado por su PSP. Descripción de NAPAS.

Del lado de la caja conviene registrar el banco, la cuenta de destino, el beneficiario que se muestra, el monto esperado, el concepto del pago, la hora de emisión de la instrucción y la vigencia del pedido. Son campos recomendados para el registro interno, no la afirmación de que todo código estático los contiene. Si el pagador ingresa el monto o la reference, hay que definir de antemano qué ocurre ante un error, la falta de texto o un pago posterior al cierre del pedido.

La ilusión peligrosa es esta: «el QR contiene el número de pedido, así que el banco devolverá el número de pedido en un campo cómodo». Hay que verificar todo el recorrido: la generación de la instrucción, la pantalla del banco del comprador, la transferencia entrante real y la exportación del beneficiario. Si el texto se recorta, se normaliza o su canal de servicio no lo transmite, eso se descubre en el piloto. No cree una acreditación automática basada en una propiedad que el contrato y las pruebas no confirmaron.

MoMo requiere un circuito comercial

El onboarding oficial de MoMo prevé, en orden, el merchant profile, la integración de prueba, la verificación de la cuenta, las production credentials, la verificación en producción y la aprobación del lanzamiento. No describe los permisos de una billetera personal. El acceso al entorno de pruebas demuestra que se puede escribir la integración, pero no que se aceptó la industria, la persona jurídica o un método de liquidación concreto.

Separe dos verificaciones: los documentos de la empresa y la capacidad del comprador de autorizar el pago. Por ejemplo, la lista vigente de códigos de MoMo incluye el rechazo 4002, vinculado a datos no verificados mediante C06 y a la necesidad de actualizar la biometría por NFC. El código 1004 corresponde a superar el límite diario o mensual, y el 1005, a una URL o un QR vencidos. Son causas distintas, y repetir la solicitud a ciegas no es una corrección.

Cinco identificadores en lugar de un «ID» difuso

En el modelo de MoMo conviene distinguir partnerCode, orderId, requestId, transId y el ID propio del pedido. El socio y el pedido definen el contexto, requestId corresponde a la solicitud y transId lo emite MoMo. Para consultar el estado se usan partnerCode, orderId, requestId y la firma. Los nombres y roles se toman de la versión concreta de la documentación; los valores se guardan sin alterar mayúsculas ni formato.

Para el registro propio, agregue el número de intento. Un pedido puede pasar por un primer intento sin pagar y un segundo exitoso. El reembolso quedará vinculado a la operación financiera exitosa, no simplemente a la última página abierta. Para cada intento guarde el monto esperado en VND y el resultado recibido; no use el nombre del producto ni el número de teléfono como clave de unicidad.

El IPN importa más que el regreso del comprador al navegador

MoMo envía el resultado al ipnUrl con un POST de servidor. La documentación exige verificar la firma y cotejar partnerCode, orderId y amount; la respuesta del receptor es HTTP 204 dentro de 15 segundos. resultCode 0 significa éxito de la operación correspondiente, y 9000, autorización exitosa. Esta última no debe considerarse automáticamente un cargo completado en un flujo con capture separado. Reglas del IPN.

El procesamiento propio debe ser idempotente: un evento monetario confirmado crea un solo registro aunque la notificación llegue repetida. El orden recomendado es verificar la solicitud, registrar el evento de forma confiable, confirmar rápido la recepción y ejecutar la entrega pesada desde una cola. Si la notificación se perdió, use la consulta oficial de estado, sin obligar al comprador a pagar de nuevo para que aparezca otro comprobante.

Hay otro límite: un HTTP 2xx indica que la solicitud a la API se procesó, pero no reemplaza la verificación del código de negocio ni del tipo de operación. Crear la página de pago, autorizar y completar el pago responden a preguntas distintas. El mensaje al usuario debe referirse al estado confirmado, no mostrar «pagado» ante cualquier respuesta técnicamente exitosa del servidor.

El reembolso es una operación aparte con su propio resultado

La Refund API de MoMo exige un orderId de reembolso nuevo, distinto del pedido original, además de requestId, monto y el transId del pago original exitoso. Existe una consulta separada del resultado del refund. Un reembolso parcial no debe superar el saldo que aún puede reembolsarse. La documentación distingue los límites numéricos según el método de pago; no se puede trasladar un mismo tope a todos los productos de MoMo.

En un caso de ejemplo, el comprador pagó 400 000 VND y luego se le aprobó un reembolso parcial. El sistema reserva el monto aprobado, lo vincula con el transId original y sigue el resultado por separado. Si la solicitud terminó por timeout, primero se averigua si fue aceptada. Crear un nuevo refund con otro identificador sin esa verificación arriesga duplicar la devolución.

Lo que queda fuera de la API de pagos

El calendario de liquidación, las comisiones, la reserva, los productos permitidos y el derecho de la empresa a cobrar los definen el contrato y las normas aplicables. La verificación de MoMo y tener una cuenta bancaria no reemplazan la autorización sectorial. En Vietnam, las autoridades explican por separado la responsabilidad por organizar juegos de azar ilegales; las reglas de los juegos en línea tampoco equiparan los objetos virtuales con dinero que se pueda retirar libremente.

Por eso no puede deducirse que un método local sirve para un negocio de juego concreto solo porque el QR se escanea o la API responde. El resultado práctico de una buena integración es otro: cada pago legal tiene un estado demostrado, un pedido vinculado, una obligación de liquidación clara y un reembolso verificable. VietQR, NAPAS 247 y MoMo cumplen papeles distintos en ese esquema, sin necesidad de inventar tres movimientos de dinero independientes.