SDK de adhesiones

La vista de gestión de adhesiones deja que tu usuario final administre su domiciliación (autopay) embebida en tu sitio, sin entrar al portal completo. Desde ahí puede:

Ver

Los medios que tiene adheridos: tarjeta o cuenta CLABE.

Adherir

Un medio nuevo, cuando todavía no tiene ninguno.

Desadherir

Un medio existente.

Usa el mismo SDK que el widget de medios de pago: misma instalación, mismas opciones de identificación de empresa y mismo destroy(). Las dos diferencias son que se monta con view: "autopay" y que emite sus propios eventos.

La instalación, los entrypoints, loadTapipay() y el entorno de homologación son idénticos. Están en SDK de medios de pago.

Uso rápido

Script tag
Data-attrs
React

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

  tapipay.on("autopayLoaded", function (data) {
    console.log("Adhesiones activas:", data.count, data.mediaTypes);
  });
</script>

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

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

export function AdhesionesPage({ clienteId }: { clienteId: string }) {
  return (
    <TapipayWidget
      organization="acme-corp"
      identifier={clienteId}
      view="autopay"
      onAutopayLoaded={(data) => console.log("Adhesiones activas:", data.count)}
      onAutopayRemoved={(data) => console.log("Medio desadherido:", data.mediaType)}
    />
  );
}

Igual que en el widget de pago, puedes identificar tu empresa con organization (el slug) o con companyCode. Reemplaza organization: "acme-corp" por companyCode: "MX-S-12345" en cualquiera de los ejemplos.

La opción `view`

Opción	Tipo	Requerido	Default	Descripción
`view`	`"payments" \| "autopay"`	No	`"payments"`	Con `"autopay"` monta la gestión de adhesiones. Omitido, monta la vista de pagos. En data-attrs: `data-view="autopay"`.

El resto de las opciones (container, organization / companyCode, identifier, environment) son las mismas que en la vista de pagos. externalRequestId y selectionStrategy no aplican acá: son de la vista de pagos. La URL que monta el SDK es la misma de la vista de pagos con /autopay al final:

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

Eventos

Privacidad. Los eventos de adhesiones exponen solo lo mínimo: el tipo de medio (mediaType) y los últimos 4 dígitos (lastFour). El id es un hash opaco, no el identificador interno. Nunca se exponen el titular, el número o CLABE completos, la marca, el banco ni tokens.

// Las adhesiones activas terminaron de cargar
tapipay.on("autopayLoaded", function (data) {
  console.log("Adhesiones activas:", data.count, data.mediaTypes);
});

// Una nueva domiciliación quedó activa
tapipay.on("autopayActivated", function (data) {
  console.log("Adhesión activa:", data.mediaType, data.lastFour);
});

// El usuario desadhirió un medio con éxito
tapipay.on("autopayRemoved", function (data) {
  console.log("Medio desadherido:", data.mediaType, data.lastFour);
});

// Falló la carga de adhesiones o la desadhesión
tapipay.on("autopayError", function (data) {
  console.log("Error de autopay:", data.stage, data.message);
});

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

Evento	Cuándo se dispara
`autopayLoaded`	Al terminar de cargar las adhesiones activas, y cada vez que el conjunto cambia (adhesión nueva, desadhesión o refetch), para que mantengas tu conteo sincronizado. No se dispara durante la carga ni ante un error de carga.
`autopayActivated`	Cuando una domiciliación nueva queda activa. Una sola vez por adhesión.
`autopayRemoved`	Cuando el usuario desadhiere un medio con éxito.
`autopayError`	Ante un fallo al cargar las adhesiones o al desadherir.

Payloads

type TapipayAutopayMediaType = "card" | "bank_account";

interface TapipayAutopayAdhesionSummary {
  id: string;                            // hash opaco de la adhesión
  mediaType: TapipayAutopayMediaType;
  lastFour: string | null;               // últimos 4 dígitos (tarjeta o CLABE)
}

interface TapipayAutopayLoadedEvent {
  count: number;                         // cantidad de adhesiones activas
  mediaTypes: TapipayAutopayMediaType[]; // tipos presentes, sin duplicados
  adhesions: TapipayAutopayAdhesionSummary[];
}

interface TapipayAutopayActivatedEvent {
  id: string;
  mediaType: TapipayAutopayMediaType;
  lastFour: string | null;
}

interface TapipayAutopayRemovedEvent {
  id: string;
  mediaType: TapipayAutopayMediaType;
  lastFour: string | null;
}

interface TapipayAutopayErrorEvent {
  stage: "load" | "remove";              // en qué fase falló
  message: string;                       // mensaje neutral, sin datos personales
}

En React

Prop	Evento equivalente
`onAutopayLoaded`	`autopayLoaded`
`onAutopayActivated`	`autopayActivated`
`onAutopayRemoved`	`autopayRemoved`
`onAutopayError`	`autopayError`

autopayLoaded se reinvoca cada vez que la lista cambia, así que te sirve como única fuente para tu contador de medios adheridos: no necesitas sumar y restar a mano con autopayActivated y autopayRemoved.

Cómo se relaciona con la API

Una deuda o suscripción creada con autopay: true se cobra por domiciliación, sin que el usuario elija un medio en cada cobro. Para que ese cobro funcione, el usuario tiene que tener un medio adherido: esta pantalla es donde lo adhiere.

Medios de pago y domiciliación

Cómo funciona autopay en deudas y suscripciones, y su relación con paymentMethods.

Empieza aquí

Conceptos

Recursos

Portal de pagos

Webhooks

SDK de adhesiones

Ver

Adherir

Desadherir

Uso rápido

La opción `view`

Eventos

Payloads

En React

Cómo se relaciona con la API

Medios de pago y domiciliación

Ver

Adherir

Desadherir

​Uso rápido

​La opción view

​Eventos

​Payloads

​En React

​Cómo se relaciona con la API

Medios de pago y domiciliación

Uso rápido

La opción `view`

Eventos

Payloads

En React

Cómo se relaciona con la API