Eventos postMessage

El iframe embebido avisa lo que va pasando adentro con mensajes postMessage al window que lo contiene:

window.parent.postMessage({ type: "TAPIPAY_DOMICILIATION_BANK_SELECTED", payload }, "*");

El SDK no hace nada mágico con eso: escucha esos mismos mensajes y los re-emite con nombres más cómodos. Esta página documenta la capa de abajo, para cuando montas el iframe a mano.

Si puedes usar el SDK, úsalo: te ahorra el listener, la validación de origen y el alto del iframe. Esta página es para cuando no puedes instalar un paquete, o ya tienes tu propio iframe montado.

Montar la vista a mano

El widget tiene dos vistas y cada una emite su propio conjunto de mensajes. Son las mismas que monta el SDK, y la URL las distingue: la de domiciliación termina en /autopay.

<iframe
  src="https://app.tapipay.la/s/acme-corp/embed/CLI-00042/autopay"
  width="100%"
  height="700"
  style="border: none;"
  allow="payment"
  title="Domiciliación"
></iframe>

<iframe
  src="https://app.tapipay.la/s/acme-corp/embed/CLI-00042"
  width="100%"
  height="700"
  style="border: none;"
  allow="payment"
  title="Medios de pago"
></iframe>

Puedes identificar tu empresa por companyCode en lugar del alias:

https://app.tapipay.la/c/MX-S-12345/embed/CLI-00042/autopay

Esto es distinto de embeber el portal completo, que muestra la lista de deudas. Aquí montas solo el widget.

Escuchar los mensajes

window.addEventListener("message", function (event) {
  // 1. Valida el origen antes de leer nada
  if (event.origin !== "https://app.tapipay.la") return;

  // 2. Enruta por el tipo de mensaje
  switch (event.data?.type) {
    case "TAPIPAY_DOMICILIATION_BANK_SELECTED":
      console.log("Banco elegido:", event.data.payload.name);
      break;
    case "TAPIPAY_DOMICILIATION_CONFIRMED":
      mostrarPantallaProcesando();
      break;
    case "TAPIPAY_AUTOPAY_ACTIVATED":
      mostrarExito(event.data.payload.lastFour);
      break;
    case "TAPIPAY_DOMICILIATION_ACCOUNT_CHECK_FAILED":
      registrar(event.data.payload.reason);
      break;
  }
});

Valida siempre event.origin. Los mensajes se emiten con targetOrigin: "*", así que tu listener recibe también lo que mande cualquier otro iframe o script de tu página. Sin ese chequeo, cualquiera puede simular un evento de TapiPay desde el navegador del usuario.

En homologación el origen es https://homo.tapipay.la.

La forma del dato no es la misma que en el SDK. El mensaje crudo es { type, payload }: el contenido viaja adentro de payload. El SDK te entrega ese payload desenvuelto al handler, pero aquí tienes que leer event.data.payload.

Señales de ciclo de vida

Las dos vistas emiten estas tres señales mientras corren dentro de un iframe, sin importar lo que haga tu usuario.

Mensaje	Cuándo llega	Datos
`TAPIPAY_JS_READY`	El widget terminó de montarse y ya puede mostrarse.	Ninguno
`TAPIPAY_READY`	Los datos cargaron y la pantalla real es visible.	Ninguno
`TAPIPAY_RESIZE`	Al montar y cada vez que cambia el alto del contenido.	`height`, en píxeles

TAPIPAY_RESIZE es la excepción a la regla del payload: el alto viaja en la raíz del mensaje, en event.data.height.

Ninguna tiene evento equivalente en el SDK, porque el SDK las resuelve por dentro: usa TAPIPAY_JS_READY para quitar su pantalla de carga y TAPIPAY_RESIZE para ajustar el alto del iframe. Si lo montas a mano, eso corre por tu cuenta.

const frame = document.querySelector("#tapipay");

window.addEventListener("message", function (event) {
  if (event.origin !== "https://app.tapipay.la") return;

  switch (event.data?.type) {
    case "TAPIPAY_JS_READY":
      ocultarPantallaDeCarga();
      break;
    case "TAPIPAY_RESIZE":
      frame.style.height = event.data.height + "px";
      break;
  }
});

Los mensajes

Cada mensaje tiene su evento equivalente en el SDK. El payload es idéntico en los dos casos, con los mismos nombres de campo.

Alta de domiciliación

Un mensaje por cada paso que tu usuario completa en el alta. Los primeros cuatro llegan una vez cada uno, en orden.

Mensaje	Evento del SDK
`TAPIPAY_DOMICILIATION_BANK_SELECTED`	`domiciliationBankSelected`
`TAPIPAY_DOMICILIATION_FORM_COMPLETED`	`domiciliationFormCompleted`
`TAPIPAY_DOMICILIATION_VERIFICATION_COMPLETED`	`domiciliationVerificationCompleted`
`TAPIPAY_DOMICILIATION_CONFIRMED`	`domiciliationConfirmed`
`TAPIPAY_DOMICILIATION_ACCOUNT_CHECK_FAILED`	`domiciliationAccountCheckFailed`

TAPIPAY_DOMICILIATION_CONFIRMED significa que tu usuario apretó confirmar, no que la adhesión quedó activa. El backend la procesa de forma asíncrona. La confirmación real es TAPIPAY_AUTOPAY_ACTIVATED.

Gestión de adhesiones

Mensaje	Evento del SDK
`TAPIPAY_AUTOPAY_LOADED`	`autopayLoaded`
`TAPIPAY_AUTOPAY_ACTIVATED`	`autopayActivated`
`TAPIPAY_AUTOPAY_REMOVED`	`autopayRemoved`
`TAPIPAY_AUTOPAY_ERROR`	`autopayError`

Pago con tarjeta

Salen de la vista de medios de pago, cuando tu usuario paga con tarjeta desde el widget.

Mensaje	Evento del SDK
`TAPIPAY_PAYMENT_WINDOW_OPENED`	`paymentWindowOpened`
`TAPIPAY_PAYMENT_SUBMITTED`	`paymentSubmitted`
`TAPIPAY_PAYMENT_CANCELLED`	`paymentCancelled`

TAPIPAY_PAYMENT_WINDOW_OPENED y TAPIPAY_PAYMENT_CANCELLED llegan sin datos: avisan que se abrió la ventana de pago y que tu usuario la cerró sin terminar.

TAPIPAY_PAYMENT_SUBMITTED significa enviado, no acreditado. Nunca des una deuda por pagada con este mensaje: el estado real llega por la notificación de pago a tu backend.

Payloads de domiciliación

Los campos de los mensajes de domiciliación y de gestión de adhesiones, con sus tipos.

Payloads de pago

Los campos de los mensajes de pago con tarjeta, con sus tipos.

Empieza aquí

Novedades

Conceptos

Recursos

Portal de pagos

Webhooks

Eventos postMessage

Montar la vista a mano

Escuchar los mensajes

Señales de ciclo de vida

Los mensajes

Alta de domiciliación

Gestión de adhesiones

Pago con tarjeta

Payloads de domiciliación

Payloads de pago

​Montar la vista a mano

​Escuchar los mensajes

​Señales de ciclo de vida

​Los mensajes

​Alta de domiciliación

​Gestión de adhesiones

​Pago con tarjeta

Payloads de domiciliación

Payloads de pago

Montar la vista a mano

Escuchar los mensajes

Señales de ciclo de vida

Los mensajes

Alta de domiciliación

Gestión de adhesiones

Pago con tarjeta