Autopay SDK

The autopay management view lets your end user manage their autopay enrollment embedded in your site, without entering the full portal. From there they can:

View

The methods they have enrolled: card or CLABE account.

Enroll

A new method, when they do not have one yet.

Remove

An existing method.

It uses the same SDK as the payment methods widget: same installation, same company identification options and same destroy(). The two differences are that it mounts with view: "autopay" and that it emits its own events.

Installation, entrypoints, loadTapipay() and the staging environment are identical. They are covered in Payment methods SDK.

Quick start

Script tag
Data-attrs
React

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

  tapipay.on("autopayLoaded", function (data) {
    console.log("Active enrollments:", 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 AutopayPage({ clientId }: { clientId: string }) {
  return (
    <TapipayWidget
      organization="acme-corp"
      identifier={clientId}
      view="autopay"
      onAutopayLoaded={(data) => console.log("Active enrollments:", data.count)}
      onAutopayRemoved={(data) => console.log("Method removed:", data.mediaType)}
    />
  );
}

Just like the payment widget, you can identify your company with organization (the slug) or with companyCode. Replace organization: "acme-corp" with companyCode: "MX-S-12345" in any of the examples.

The `view` option

Option	Type	Required	Default	Description
`view`	`"payments" \| "autopay"`	No	`"payments"`	With `"autopay"` it mounts autopay management. Omitted, it mounts the payments view. In data-attrs: `data-view="autopay"`.

Every other option (container, organization / companyCode, identifier, environment) is the same as in the payments view. externalRequestId and selectionStrategy do not apply here: they belong to the payments view. The URL the SDK mounts is the payments view URL with /autopay appended:

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

Events

Privacy. Autopay events expose only the minimum: the method type (mediaType) and the last 4 digits (lastFour). The id is an opaque hash, not the internal identifier. The holder name, the full number or CLABE, the brand, the bank and tokens are never exposed.

// Active enrollments finished loading
tapipay.on("autopayLoaded", function (data) {
  console.log("Active enrollments:", data.count, data.mediaTypes);
});

// A new autopay enrollment became active
tapipay.on("autopayActivated", function (data) {
  console.log("Enrollment active:", data.mediaType, data.lastFour);
});

// The user successfully removed a method
tapipay.on("autopayRemoved", function (data) {
  console.log("Method removed:", data.mediaType, data.lastFour);
});

// Loading enrollments or removing one failed
tapipay.on("autopayError", function (data) {
  console.log("Autopay error:", data.stage, data.message);
});

// Remove a listener
tapipay.off("autopayLoaded", handler);

Event	When it fires
`autopayLoaded`	When active enrollments finish loading, and every time the set changes (new enrollment, removal or refetch), so you can keep your count in sync. It does not fire during loading or on a load error.
`autopayActivated`	When a new autopay enrollment becomes active. Once per enrollment.
`autopayRemoved`	When the user successfully removes a method.
`autopayError`	On a failure loading enrollments or removing one.

Payloads

type TapipayAutopayMediaType = "card" | "bank_account";

interface TapipayAutopayAdhesionSummary {
  id: string;                            // opaque hash of the enrollment
  mediaType: TapipayAutopayMediaType;
  lastFour: string | null;               // last 4 digits (card or CLABE)
}

interface TapipayAutopayLoadedEvent {
  count: number;                         // number of active enrollments
  mediaTypes: TapipayAutopayMediaType[]; // types present, no duplicates
  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";              // which phase failed
  message: string;                       // neutral message, no personal data
}

In React

Prop	Matching event
`onAutopayLoaded`	`autopayLoaded`
`onAutopayActivated`	`autopayActivated`
`onAutopayRemoved`	`autopayRemoved`
`onAutopayError`	`autopayError`

autopayLoaded fires again every time the list changes, so you can use it as the single source for your enrolled methods counter: no need to add and subtract by hand with autopayActivated and autopayRemoved.

How it relates to the API

A debt or subscription created with autopay: true is charged through autopay, without the user picking a method on every charge. For that charge to work, the user needs an enrolled method: this screen is where they enroll it.

Payment methods and autopay

How autopay works on debts and subscriptions, and how it relates to paymentMethods.

Get started

Concepts

Resources

Payment portal

Webhooks

View

Enroll

Remove

Quick start

The `view` option

Events

Payloads

In React

How it relates to the API

Payment methods and autopay

View

Enroll

Remove

​Quick start

​The view option

​Events

​Payloads

​In React

​How it relates to the API

Payment methods and autopay

Quick start

The `view` option

Events

Payloads

In React

How it relates to the API