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" | "debit_card";

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
}

mediaType tells the enrolled method apart: card is a credit card, bank_account is a CLABE account and debit_card is a debit card.

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.

Enrollment flow events

When the user does not have an enrolled method yet, the autopay view opens the enrollment flow inside the same iframe. That flow emits its own events, one per step the user completes, so you can follow their progress from your site.

These are interface milestones: they tell you what the user completed in the widget, not what the backend confirmed. The enrollment is processed asynchronously, so the confirmation that it became active arrives through autopayActivated.

The first four form a sequence. They fire once each, in this order:

domiciliationBankSelected

The user picked their bank.

domiciliationFormCompleted

The account details passed backend validation.

domiciliationVerificationCompleted

Account verification finished.

domiciliationConfirmed

The user confirmed the enrollment.

The fifth one, domiciliationAccountCheckFailed, is not part of that sequence: it is an error event that can fire zero, one or many times while the user types their CLABE or card number. It is the equivalent of autopayError for this flow.

Underneath, these events are postMessage messages the iframe emits. If you embed it by hand, without the SDK, you can listen to them directly: see postMessage events.

Privacy. Unlike the autopay events, these events do carry the bank identity (bankId, speiCode, name), because you embed the widget for your own customers. What never travels is the holder data or the full account: not the name, the email, the RFC, the full CLABE or card number, or tokens. From the account, only the type (accountType) and the last 4 digits (lastFour) are exposed.

// The user picked their bank
tapipay.on("domiciliationBankSelected", function (data) {
  console.log("Bank picked:", data.name);
});

// The account details passed validation
tapipay.on("domiciliationFormCompleted", function (data) {
  console.log("Account validated:", data.accountType, data.lastFour);
});

// Account verification finished
tapipay.on("domiciliationVerificationCompleted", function (data) {
  console.log("Verification:", data.method, data.outcome);
});

// The user confirmed the enrollment
tapipay.on("domiciliationConfirmed", function (data) {
  console.log("Confirmed:", data.enrollAllDebts, data.selectedProductsCount);
  // Show "we are registering your autopay" and wait for `autopayActivated`
});

// The live check on the CLABE or card rejected the value
tapipay.on("domiciliationAccountCheckFailed", function (data) {
  console.log("Check rejected:", data.bankId, data.reason);
});

Event	When it fires
`domiciliationBankSelected`	When the user picks their bank. It fires on every selection change.
`domiciliationFormCompleted`	When the account details pass backend validation.
`domiciliationVerificationCompleted`	When account verification finishes, with any method. The validation step is conditional: if the backend does not require it, or the method is not `penny`, the widget skips it and the event fires anyway. Treat it as a guaranteed milestone of the flow.
`domiciliationConfirmed`	When the user confirms the enrollment. It does not mean it became active: wait for `autopayActivated`.
`domiciliationAccountCheckFailed`	When the live check on the CLABE or card rejects the value the user currently has typed. It can fire many times and does not prevent the others from arriving if the user fixes the value.

Payloads

interface TapipayDomiciliationBankSelectedEvent {
  bankId: string;    // bank id in the TapiPay catalog
  speiCode: string;  // SPEI code of the bank
  name: string;      // commercial name of the bank
}

interface TapipayDomiciliationFormCompletedEvent {
  bankId: string;
  accountType: "BANK_ACCOUNT" | "DEBIT_CARD";
  lastFour: string | null;               // last 4 digits of the CLABE or card
}

interface TapipayDomiciliationVerificationCompletedEvent {
  method: "penny" | "kyc" | "transfer";  // method used to verify the account
  outcome: "approved" | "failed";
}

interface TapipayDomiciliationConfirmedEvent {
  enrollAllDebts: boolean;               // true if they enrolled all their debts
  selectedProductsCount: number;         // how many services they selected
}

interface TapipayDomiciliationAccountCheckFailedEvent {
  bankId: string;
  reason: "checksum" | "plaza" | "luhn" | "card_type_blocked" | "bank_mismatch";
}

`domiciliationAccountCheckFailed` reasons

The CLABE or card the user typed never travels, and neither does the error message they see on screen (that text belongs to the interface and can change without notice). Only the selected bank and the categorized reason.

`reason`	What happened
`checksum`	The CLABE check digit is not valid.
`plaza`	The CLABE locality code (`plaza`) is not in the ABM catalog.
`luhn`	The card number fails Luhn validation.
`card_type_blocked`	The card type is not accepted: credit and prepaid cards are rejected.
`bank_mismatch`	The CLABE or card does not belong to the bank the user selected.

In React

Prop	Matching event
`onDomiciliationBankSelected`	`domiciliationBankSelected`
`onDomiciliationFormCompleted`	`domiciliationFormCompleted`
`onDomiciliationVerificationCompleted`	`domiciliationVerificationCompleted`
`onDomiciliationConfirmed`	`domiciliationConfirmed`
`onDomiciliationAccountCheckFailed`	`domiciliationAccountCheckFailed`

<TapipayWidget
  organization="acme-corp"
  identifier={customerId}
  view="autopay"
  onDomiciliationConfirmed={() => showProcessingScreen()}
  onDomiciliationAccountCheckFailed={(data) => track(data.reason)}
  onAutopayActivated={(data) => showSuccess(data.lastFour)}
/>

To measure where your users drop off, track the four milestones in order and compare how many reach each one. domiciliationAccountCheckFailed also tells you which detail blocks them from moving forward.

How it relates to the API

A subscription created with autopay: true is charged through autopay, without the user picking a method on every charge. In direct debit (POST /v2/debts) the debt does not carry autopay: it is debited automatically if it references a product and the user has an enrolled default method. 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

What's new

Concepts

Resources

Payment portal

Webhooks

View

Enroll

Remove

Quick start

The `view` option

Events

Payloads

In React

Enrollment flow events

Payloads

`domiciliationAccountCheckFailed` reasons

In React

How it relates to the API

Payment methods and autopay

View

Enroll

Remove

​Quick start

​The view option

​Events

​Payloads

​In React

​Enrollment flow events

​Payloads

​domiciliationAccountCheckFailed reasons

​In React

​How it relates to the API

Payment methods and autopay

Quick start

The `view` option

Events

Payloads

In React

Enrollment flow events

Payloads

`domiciliationAccountCheckFailed` reasons

In React

How it relates to the API