> ## Documentation Index
> Fetch the complete documentation index at: https://devs.tapipay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK de adhesiones

> Embebe la pantalla de gestión de domiciliación para que tu usuario administre sus medios adheridos.

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:

<CardGroup cols={3}>
  <Card title="Ver" icon="eye">
    Los medios que tiene adheridos: tarjeta o cuenta CLABE.
  </Card>

  <Card title="Adherir" icon="plus">
    Un medio nuevo, cuando todavía no tiene ninguno.
  </Card>

  <Card title="Desadherir" icon="trash">
    Un medio existente.
  </Card>
</CardGroup>

Usa el **mismo SDK** que el [widget de medios de pago](/es/portal-de-pagos/sdk-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.

<Note>
  La instalación, los entrypoints, `loadTapipay()` y el entorno de homologación son idénticos. Están en [SDK de medios de pago](/es/portal-de-pagos/sdk-medios-de-pago#instalación).
</Note>

## Uso rápido

<Tabs>
  <Tab title="Script tag">
    ```html theme={null}
    <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>
    ```
  </Tab>

  <Tab title="Data-attrs">
    ```html theme={null}
    <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>
    ```
  </Tab>

  <Tab title="React">
    ```tsx theme={null}
    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)}
        />
      );
    }
    ```
  </Tab>
</Tabs>

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](/es/portal-de-pagos/sdk-medios-de-pago#opciones). `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:

```text theme={null}
https://app.tapipay.la/s/acme-corp/embed/CLI-00042/autopay
https://app.tapipay.la/c/MX-S-12345/embed/CLI-00042/autopay
```

## Eventos

<Warning>
  **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.
</Warning>

```javascript theme={null}
// 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

```typescript theme={null}
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`     |

<Tip>
  `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`.
</Tip>

## 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.

<Card title="Medios de pago y domiciliación" icon="credit-card" href="/es/conceptos/medios-de-pago">
  Cómo funciona `autopay` en deudas y suscripciones, y su relación con `paymentMethods`.
</Card>