SDK de medios de pago

El SDK de embed monta el widget de pago de TapiPay dentro de tu sitio. A diferencia de un iframe manual, ajusta su alto solo, muestra un skeleton mientras carga y te avisa por eventos qué está haciendo el usuario. Es el mismo SDK que usa la gestión de adhesiones: cambia una sola opción (view) para montar una vista u otra.

Instalación

npm install @npmtapi/embed

pnpm add @npmtapi/embed

yarn add @npmtapi/embed

Los tipos de TypeScript vienen incluidos en el paquete. No necesitas instalar nada aparte.

Entrypoints

Import	Qué expone
`@npmtapi/embed`	`loadTapipay()` y todos los tipos
`@npmtapi/embed/react`	`<TapipayWidget />` y `useTapipay()`

<TapipayWidget /> es el camino recomendado en React: se encarga de cargar el SDK, montar el widget y limpiarlo al desmontar. useTapipay() es el hook de bajo nivel, para cuando necesitas controlar initialize() y destroy() a mano. Si no usas bundler, no hace falta instalar nada: carga el script y trabaja con window.tapipay.

Identifica tu empresa

Pasa una de estas dos opciones, no las dos:

string

El slug o alias de tu empresa (por ejemplo, acme-corp). Corresponde al campo Alias en Configuración → Organización del dashboard. En data-attrs: data-organization.

string

El código de empresa configurado para tu organización en TapiPay (por ejemplo, MX-S-12345). El formato varía entre integraciones: si no sabes cuál es el tuyo, confírmalo con tu contacto de TapiPay. En data-attrs: data-company-code.

Si manejas muchas empresas o sub-billers, usa companyCode: no necesitas conocer ni administrar el slug de cada una. Si pasas las dos opciones, companyCode gana.

Todos los ejemplos de esta página funcionan igual si reemplazas organization: "acme-corp" por companyCode: "MX-S-12345".

Uso rápido

Script tag
Data-attrs
React

Sin bundler. El script deja window.tapipay disponible al cargar.

<div id="widget"></div>
<script src="https://app.tapipay.la/embed.js"></script>
<script>
  tapipay.initialize({
    container: "#widget",
    organization: "acme-corp",
    identifier: "CLI-00042"
  });

  tapipay.on("paymentSubmitted", function (data) {
    console.log("Pago enviado:", data);
  });
</script>

Cero JavaScript. El SDK busca los contenedores con data-tapipay-widget y los monta al cargar el DOM.

<div
  data-tapipay-widget
  data-organization="acme-corp"
  data-identifier="CLI-00042"
></div>
<script src="https://app.tapipay.la/embed.js"></script>

import { TapipayWidget } from "@npmtapi/embed/react";

export function PagoPage({ clienteId }: { clienteId: string }) {
  return (
    <TapipayWidget
      organization="acme-corp"
      identifier={clienteId}
      onPaymentSubmitted={(data) => console.log("Pago enviado:", data)}
      onCancelled={() => console.log("Pago cancelado por el usuario")}
    />
  );
}

Opciones

`initialize(options)`

Opción	Tipo	Requerido	Default	Descripción
`container`	`string \| HTMLElement`	Sí		Selector CSS o referencia al nodo del DOM donde se monta el widget.
`organization`	`string`	Sí*		`slug` de tu empresa. *Requerido salvo que pases `companyCode`.
`companyCode`	`string`	Sí*		Código de empresa. *Alternativa a `organization`; si pasas las dos, esta gana.
`identifier`	`string`	Sí		Identificador del usuario final (el mismo que envías al crear la deuda).
`externalRequestId`	`string`	No		Deuda a preseleccionar. Tiene precedencia sobre `selectionStrategy`.
`selectionStrategy`	`"oldestCreated"`	No	la más reciente	Cómo elegir la deuda pendiente cuando hay varias. Omitido: la más reciente.
`view`	`"payments" \| "autopay"`	No	`"payments"`	Vista a montar. Con `"autopay"` monta la gestión de adhesiones.

Si faltan container, identifier o los dos identificadores de empresa, el SDK no monta nada y avisa por consola.

`destroy(container)`

Desmonta el widget: quita el iframe, el skeleton y los listeners internos.

tapipay.destroy("#widget");

Llamarlo es importante en una SPA, al desmontar el componente que contiene el widget. <TapipayWidget /> ya lo hace por ti. Si vuelves a llamar initialize() sobre un contenedor que ya tiene un widget, el SDK lo destruye y lo vuelve a montar.

`loadTapipay(options)`

Opción	Tipo	Requerido	Default	Descripción
`environment`	`"production" \| "homo"`	No	`"production"`	Entorno del SDK a cargar.

Es idempotente por entorno: llamarlo varias veces devuelve la misma promesa y no inyecta el script dos veces. Es compatible con React Strict Mode.

Eventos

// El popup de pago se abrió
tapipay.on("paymentWindowOpened", function () {
  console.log("Ventana de pago abierta");
});

// El usuario completó el formulario y volvió al callback
tapipay.on("paymentSubmitted", function (data) {
  console.log("Pago enviado:", data);
});

// El usuario cerró el popup sin pagar
tapipay.on("paymentCancelled", function () {
  console.log("Pago cancelado por el usuario");
});

// Quitar un listener
tapipay.off("paymentSubmitted", handler);

paymentSubmitted significa enviado, no confirmado. Su status es siempre "pending": el usuario completó el formulario, pero el pago todavía no está acreditado. Nunca marques una deuda como pagada con este evento. El estado real llega por la notificación de pago a tu backend.

Payloads

interface TapipayPaymentWindowOpenedEvent {
  type: "paymentWindowOpened";
}

interface TapipayPaymentSubmittedEvent {
  type: string;                    // "TAPIPAY_CALLBACK"
  status: "pending";               // siempre pending
  data: Record<string, string>;    // params del callback (pueden venir vacíos)
}

type TapipayPaymentCancelledEvent = Record<string, never>;  // sin campos

En React

Los eventos se pasan como props. Ojo con el nombre del tercero: el evento se llama paymentCancelled, pero la prop es onCancelled.

Prop	Evento equivalente
`onPaymentWindowOpened`	`paymentWindowOpened`
`onPaymentSubmitted`	`paymentSubmitted`
`onCancelled`	`paymentCancelled`

<TapipayWidget /> acepta además todas las opciones de initialize() (menos container), más environment, className y style para el contenedor.

Otros frameworks

Next.js
Vue 3
Angular

"use client";
import { TapipayWidget } from "@npmtapi/embed/react";
import { useRouter } from "next/navigation";

export default function PagarPage() {
  const router = useRouter();
  return (
    <TapipayWidget
      organization="acme-corp"
      identifier="CLI-00042"
      onPaymentSubmitted={() => router.push("/procesando")}
    />
  );
}

El widget es un componente de cliente: necesita "use client".

<template>
  <div ref="widgetRef"></div>
</template>

<script setup>
import { loadTapipay } from "@npmtapi/embed";
import { onMounted, onUnmounted, ref } from "vue";

const props = defineProps({ organization: String, identifier: String });
const widgetRef = ref(null);
let tapipay = null;

onMounted(async () => {
  tapipay = await loadTapipay();
  tapipay.initialize({
    container: widgetRef.value,
    organization: props.organization,
    identifier: props.identifier
  });
  tapipay.on("paymentSubmitted", (data) => console.log("Pago enviado:", data));
});

onUnmounted(() => tapipay?.destroy(widgetRef.value));
</script>

import { loadTapipay, TapipayInstance } from "@npmtapi/embed";
import { Component, ElementRef, Input, OnDestroy, OnInit, ViewChild } from "@angular/core";

@Component({
  selector: "app-tapipay-widget",
  template: `<div #container></div>`
})
export class TapipayWidgetComponent implements OnInit, OnDestroy {
  @Input() organization!: string;
  @Input() identifier!: string;
  @ViewChild("container", { static: true }) containerRef!: ElementRef;

  private tapipay: TapipayInstance | null = null;

  async ngOnInit() {
    this.tapipay = await loadTapipay();
    this.tapipay.initialize({
      container: this.containerRef.nativeElement,
      organization: this.organization,
      identifier: this.identifier
    });
  }

  ngOnDestroy() {
    this.tapipay?.destroy(this.containerRef.nativeElement);
  }
}

Entorno de homologación

npm
React
Script tag

import { loadTapipay } from "@npmtapi/embed";

const tapipay = await loadTapipay({ environment: "homo" });
tapipay.initialize({
  container: "#widget",
  organization: "acme-corp",
  identifier: "CLI-00042"
});

<TapipayWidget
  organization="acme-corp"
  identifier="CLI-00042"
  environment="homo"
/>

Apunta el src al host de homologación.

<script src="https://homo.tapipay.la/embed.js"></script>

Entorno	Script	Origen del widget
`production`	`https://app.tapipay.la/embed.js`	`https://app.tapipay.la`
`homo`	`https://homo.tapipay.la/embed.js`	`https://homo.tapipay.la`

Qué monta el SDK

Saber qué URL construye el SDK ayuda a depurar: si el widget queda en blanco, abre esa URL directo en el navegador y vas a ver el error real.

Vista	URL del iframe
Pagos, por `organization`	`{origen}/s/{organization}/embed/{identifier}`
Pagos, por `companyCode`	`{origen}/c/{companyCode}/embed/{identifier}`
Adhesiones	la misma, con `/autopay` al final

externalRequestId y selectionStrategy se agregan como query params. Por ejemplo, initialize() con organization: "acme-corp", identifier: "CLI-00042" y externalRequestId: "INV-2026-001" monta:

https://app.tapipay.la/s/acme-corp/embed/CLI-00042?externalRequestId=INV-2026-001

Empieza aquí

Conceptos

Recursos

Portal de pagos

Webhooks

SDK de medios de pago

Instalación

Entrypoints

Identifica tu empresa

Uso rápido

Opciones

`initialize(options)`

`destroy(container)`

`loadTapipay(options)`

Eventos

Payloads

En React

Otros frameworks

Entorno de homologación

Qué monta el SDK

​Instalación

​Entrypoints

​Identifica tu empresa

​Uso rápido

​Opciones

​initialize(options)

​destroy(container)

​loadTapipay(options)

​Eventos

​Payloads

​En React

​Otros frameworks

​Entorno de homologación

​Qué monta el SDK

Instalación

Entrypoints

Identifica tu empresa

Uso rápido

Opciones

`initialize(options)`

`destroy(container)`

`loadTapipay(options)`

Eventos

Payloads

En React

Otros frameworks

Entorno de homologación

Qué monta el SDK