Payment methods SDK

The embed SDK mounts the TapiPay payment widget inside your site. Unlike a manual iframe, it resizes itself, shows a skeleton while loading, and tells you through events what the user is doing. It is the same SDK used by autopay management: a single option (view) decides which screen you mount.

Installation

npm install @npmtapi/embed

pnpm add @npmtapi/embed

yarn add @npmtapi/embed

TypeScript types ship with the package. You do not need to install anything else.

Entrypoints

Import	What it exposes
`@npmtapi/embed`	`loadTapipay()` and all types
`@npmtapi/embed/react`	`<TapipayWidget />` and `useTapipay()`

<TapipayWidget /> is the recommended path in React: it loads the SDK, mounts the widget and cleans it up on unmount. useTapipay() is the low level hook, for when you need to control initialize() and destroy() yourself. If you are not using a bundler, you do not need to install anything: load the script and work with window.tapipay.

Identify your company

Pass one of these two options, not both:

string

Your company’s slug or alias (for example, acme-corp). It matches the Alias field under Settings → Organization in the dashboard. In data-attrs: data-organization.

string

The company code configured for your organization in TapiPay (for example, MX-S-12345). The format varies between integrations: if you do not know yours, confirm it with your TapiPay contact. In data-attrs: data-company-code.

If you manage many companies or sub-billers, use companyCode: you do not need to know or maintain each company’s slug. If you pass both, companyCode wins.

Every example on this page works the same if you replace organization: "acme-corp" with companyCode: "MX-S-12345".

Quick start

Script tag
Data-attrs
React

No bundler. The script makes window.tapipay available once loaded.

<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("Payment submitted:", data);
  });
</script>

Zero JavaScript. The SDK looks for containers with data-tapipay-widget and mounts them once the DOM is ready.

<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 PaymentPage({ clientId }: { clientId: string }) {
  return (
    <TapipayWidget
      organization="acme-corp"
      identifier={clientId}
      onPaymentSubmitted={(data) => console.log("Payment submitted:", data)}
      onCancelled={() => console.log("Payment cancelled by the user")}
    />
  );
}

Options

`initialize(options)`

Option	Type	Required	Default	Description
`container`	`string \| HTMLElement`	Yes		CSS selector or DOM node reference where the widget mounts.
`organization`	`string`	Yes*		Your company `slug`. *Required unless you pass `companyCode`.
`companyCode`	`string`	Yes*		Company code. *Alternative to `organization`; if you pass both, this one wins.
`identifier`	`string`	Yes		End user identifier (the same one you send when creating the debt).
`externalRequestId`	`string`	No		Debt to preselect. Takes precedence over `selectionStrategy`.
`selectionStrategy`	`"oldestCreated"`	No	most recent	How to pick the pending debt when there are several. Omitted: the most recent one.
`view`	`"payments" \| "autopay"`	No	`"payments"`	Which screen to mount. With `"autopay"` it mounts autopay management.

If container, identifier or both company identifiers are missing, the SDK mounts nothing and warns in the console.

`destroy(container)`

Unmounts the widget: removes the iframe, the skeleton and the internal listeners.

tapipay.destroy("#widget");

Calling it matters in a SPA, when unmounting the component that holds the widget. <TapipayWidget /> already does it for you. If you call initialize() again on a container that already has a widget, the SDK destroys it and mounts it again.

`loadTapipay(options)`

Option	Type	Required	Default	Description
`environment`	`"production" \| "homo"`	No	`"production"`	Which SDK environment to load.

It is idempotent per environment: calling it several times returns the same promise and never injects the script twice. It is compatible with React Strict Mode.

Events

// The payment popup opened
tapipay.on("paymentWindowOpened", function () {
  console.log("Payment window opened");
});

// The user completed the form and came back to the callback
tapipay.on("paymentSubmitted", function (data) {
  console.log("Payment submitted:", data);
});

// The user closed the popup without paying
tapipay.on("paymentCancelled", function () {
  console.log("Payment cancelled by the user");
});

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

paymentSubmitted means submitted, not confirmed. Its status is always "pending": the user completed the form, but the payment is not settled yet. Never mark a debt as paid based on this event. The real status arrives through the payment notification to your backend.

Payloads

interface TapipayPaymentWindowOpenedEvent {
  type: "paymentWindowOpened";
}

interface TapipayPaymentSubmittedEvent {
  type: string;                    // "TAPIPAY_CALLBACK"
  status: "pending";               // always pending
  data: Record<string, string>;    // callback params (may come back empty)
}

type TapipayPaymentCancelledEvent = Record<string, never>;  // no fields

In React

Events are passed as props. Watch out for the third name: the event is called paymentCancelled, but the prop is onCancelled.

Prop	Matching event
`onPaymentWindowOpened`	`paymentWindowOpened`
`onPaymentSubmitted`	`paymentSubmitted`
`onCancelled`	`paymentCancelled`

<TapipayWidget /> also accepts every initialize() option (except container), plus environment, className and style for the container.

Other frameworks

Next.js
Vue 3
Angular

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

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

The widget is a client component: it needs "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("Payment submitted:", 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);
  }
}

Staging environment

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"
/>

Point src at the staging host.

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

Environment	Script	Widget origin
`production`	`https://app.tapipay.la/embed.js`	`https://app.tapipay.la`
`homo`	`https://homo.tapipay.la/embed.js`	`https://homo.tapipay.la`

What the SDK mounts

Knowing which URL the SDK builds helps you debug: if the widget stays blank, open that URL directly in the browser and you will see the real error.

View	Iframe URL
Payments, by `organization`	`{origin}/s/{organization}/embed/{identifier}`
Payments, by `companyCode`	`{origin}/c/{companyCode}/embed/{identifier}`
Autopay	the same, with `/autopay` appended

externalRequestId and selectionStrategy are added as query params. For example, initialize() with organization: "acme-corp", identifier: "CLI-00042" and externalRequestId: "INV-2026-001" mounts:

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

Get started

Concepts

Resources

Payment portal

Webhooks

Payment methods SDK

Installation

Entrypoints

Identify your company

Quick start

Options

`initialize(options)`

`destroy(container)`

`loadTapipay(options)`

Events

Payloads

In React

Other frameworks

Staging environment

What the SDK mounts

​Installation

​Entrypoints

​Identify your company

​Quick start

​Options

​initialize(options)

​destroy(container)

​loadTapipay(options)

​Events

​Payloads

​In React

​Other frameworks

​Staging environment

​What the SDK mounts

Installation

Entrypoints

Identify your company

Quick start

Options

`initialize(options)`

`destroy(container)`

`loadTapipay(options)`

Events

Payloads

In React

Other frameworks

Staging environment

What the SDK mounts