SDK para apps móviles

El SDK nativo de TapiPay abre el widget de pago dentro de tu app de Android o iOS, en una pantalla propia del SDK, y te avisa por eventos qué está haciendo el usuario. Es el equivalente móvil del SDK de medios de pago: monta las mismas vistas (pagos y gestión de adhesiones) y usa los mismos datos para identificar a tu empresa y a tu usuario.

Android

Kotlin, Jetpack Compose o Views. Se instala con Gradle.

iOS

Swift, SwiftUI o UIKit. Se instala con Swift Package Manager.

Cómo funciona

Tu app llama a Tapipay.present(...) (o muestra el TapipayButton del SDK) con el identificador del usuario y el de tu empresa.
El SDK abre el widget de TapiPay en una pantalla nativa, encima de tu app.
Mientras el usuario paga o administra sus adhesiones, el SDK te entrega eventos en un callback.
Tu app cierra el widget cuando lo necesita, o el usuario lo cierra con el botón Cerrar o el gesto atrás.

Ningún evento del SDK confirma un pago. Cuando llega PaymentSubmitted (Android) o .paymentSubmitted (iOS), el usuario envió el pago, pero todavía no está acreditado. El estado real llega a tu backend por la notificación de pago.

Requisitos

	Android	iOS
Versión mínima del sistema	Android 8.0 (`minSdk` 26)	iOS 16
Lenguaje	Kotlin	Swift
Herramientas	JDK 17 o superior para compilar	Xcode 26 o superior
Distribución	Repositorio Maven de TapiPay	Swift Package Manager
Versión actual del SDK	`0.1.0`	`0.1.0`

En los dos casos necesitas:

El identificador de tu usuario final (identifier), el mismo que envías al crear la deuda.
El alias de tu empresa (organization) o tu código de empresa (companyCode). Funcionan igual que en el SDK web: ver Identifica tu empresa.

Android

1. Agrega el repositorio de TapiPay

El SDK se distribuye por un repositorio Maven propio de TapiPay. Agrégalo en el settings.gradle.kts de tu proyecto:

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://sdk-tapipay.apps.tapila.cloud/maven") // TapiPay Maven repository
    }
}

2. Agrega la dependencia

En el build.gradle.kts del módulo de tu app:

build.gradle.kts

dependencies {
    implementation("la.tapipay.ui:button:0.1.0")
}

El artefacto se llama button por compatibilidad, pero incluye el SDK completo: la pantalla del widget, los eventos y el botón opcional.

No necesitas tocar tu AndroidManifest.xml: el SDK ya declara el permiso INTERNET y su propia pantalla. Tampoco necesitas reglas de ProGuard o R8: el SDK trae las suyas. El SDK incluye Jetpack Compose y Material 3 como dependencias. Si tu app usa Views (XML), igual puedes abrir el widget con Tapipay.present(); solo TapipayButton requiere Compose. Llama a Tapipay.present() desde cualquier Context (idealmente una Activity):

import la.tapipay.ui.button.Tapipay
import la.tapipay.ui.button.TapipayConfig
import la.tapipay.ui.button.TapipayEnvironment
import la.tapipay.ui.button.TapipayEvent

Tapipay.present(
    context = this,
    config = TapipayConfig(
        identifier = "CLI-00042",
        organization = "acme-corp", // or companyCode = "MX-S-12345"
        environment = TapipayEnvironment.HOMO, // omit it in production
    ),
) { event ->
    when (event) {
        TapipayEvent.PaymentWindowOpened -> Unit
        is TapipayEvent.PaymentSubmitted -> {
            // Submitted, not settled: show "processing" until the webhook arrives.
            showProcessing(event.paymentId)
        }
        is TapipayEvent.PaymentFailed -> Unit // the user can retry inside the widget
        TapipayEvent.PaymentCancelled -> Unit
        TapipayEvent.Dismissed -> Unit        // the user closed the widget
        is TapipayEvent.LoadFailed -> showError(event.reason)
        else -> Unit                          // required, see below
    }
}

present() lanza IllegalArgumentException si la configuración es inválida: falta identifier, no pasas organization ni companyCode, o usas selectionStrategy con la vista de adhesiones. El callback de eventos siempre se invoca en el hilo principal. El widget no se cierra solo después de un pago. Ciérralo tú cuando lo necesites:

Tapipay.dismiss()

dismiss() no emite ningún evento (tú ya sabes que lo cerraste) y no hace nada si no hay un widget abierto. Puedes llamarlo desde cualquier hilo.

Botón de Compose (opcional)

Si tu app usa Jetpack Compose, TapipayButton muestra un botón de Material 3 que abre el widget al tocarlo:

import la.tapipay.ui.button.TapipayButton
import la.tapipay.ui.button.TapipayButtonConfig

TapipayButton(
    config = TapipayConfig(identifier = "CLI-00042", organization = "acme-corp"),
    button = TapipayButtonConfig(text = "Pay my bill"),
    onEvent = { event -> viewModel.onTapipayEvent(event) },
)

Toma los colores y la tipografía de tu MaterialTheme. Si pasas onClick, el botón no abre el widget y te delega el toque.

Opciones de `TapipayConfig`

Opción	Tipo	Requerido	Default	Descripción
`identifier`	`String`	Sí		Identificador del usuario final.
`organization`	`String?`	Sí*	`null`	`slug` de tu empresa. *Requerido salvo que pases `companyCode`.
`companyCode`	`String?`	Sí*	`null`	Código de empresa. *Alternativa a `organization`; si pasas las dos, esta gana.
`view`	`TapipayView`	No	`PAYMENTS`	`PAYMENTS` monta la vista de pagos; `AUTOPAY`, la gestión de adhesiones.
`environment`	`TapipayEnvironment`	No	`PRODUCTION`	`PRODUCTION` o `HOMO` (homologación).
`externalRequestId`	`String?`	No	`null`	Deuda a preseleccionar.
`selectionStrategy`	`TapipaySelectionStrategy?`	No	`null`	`OLDEST_CREATED` elige la deuda pendiente más antigua. Solo en `PAYMENTS`.
`appearance`	`TapipayAppearance`	No	tema de tu app	Barra superior nativa del widget. Ver Apariencia.

Eventos en Android

TapipayEvent es una sealed interface:

Evento	Cuándo llega
`PaymentWindowOpened`	Se abrió la ventana de pago del proveedor.
`PaymentSubmitted(paymentId, status, data)`	El usuario envió el pago. `status` es `PENDING` o `SUCCEEDED`. No es la acreditación.
`PaymentFailed(paymentId, status, reason)`	El pago fue rechazado o quedó pendiente de una acción (por ejemplo, 3DS). El usuario sigue en el widget y puede reintentar.
`PaymentCancelled`	El usuario cerró la ventana de pago sin completar el flujo.
`Dismissed`	El usuario cerró el widget (botón Cerrar o atrás). Es el último evento de la sesión. No llega cuando lo cierras con `Tapipay.dismiss()`.
`LoadFailed(reason)`	El widget no pudo cargar (sin red, error del servidor).
`AutopayLoaded`, `AutopayActivated`, `AutopayRemoved`, `AutopayError`	Eventos de la gestión de adhesiones.

Incluye siempre una rama else -> en tu when. En versiones nuevas del SDK pueden sumarse eventos: sin else, tu código deja de compilar o ignora el evento sin aviso. Kotlin puede marcar el else como redundante; déjalo igual.

Apariencia en Android

TapipayAppearance configura la barra superior nativa que envuelve al widget. Si no pasas nada, usa los colores de tu MaterialTheme.

Opción	Tipo	Default	Descripción
`title`	`String?`	”Pagar”	Título de la barra.
`showToolbar`	`Boolean`	`true`	Con `false`, el widget ocupa toda la pantalla y se cierra con el botón atrás del sistema.
`closeText`	`String?`	”Cerrar”	Texto del botón de cierre.
`closeContentDescription`	`String?`	`closeText`	Texto que lee TalkBack para el botón de cierre.
`toolbarContainerColorArgb`	`Int?`	tema	Color de fondo de la barra (ARGB).
`toolbarContentColorArgb`	`Int?`	tema	Color del título y del botón de cierre (ARGB).

También puedes redefinir los textos por default en tu app con los recursos tapipay_button_text, tapipay_checkout_title, tapipay_checkout_close y tapipay_checkout_load_failed.

Buenas prácticas en Android

Un widget a la vez. Si llamas present() con un widget ya abierto (por ejemplo, por un doble toque), la llamada se ignora.
No captures la Activity en el callback. El SDK retiene el callback mientras el widget está abierto. Reenvía los eventos a un ViewModel o revisa el Lifecycle antes de tocar la UI.
Rotación y modo oscuro no recrean la pantalla del widget. Si Android destruye la pantalla por falta de memoria, el widget se recarga y el usuario tiene que volver a cargar los datos del formulario.

iOS

1. Agrega el paquete

El SDK se distribuye por Swift Package Manager desde este repositorio:

https://bitbucket.org/tapila/tapi-tapipay-ios-sdk

Xcode
Package.swift

Abre File → Add Package Dependencies…
Pega la URL del repositorio.
En Dependency Rule, elige Up to Next Minor Version desde 0.1.0.
Agrega el producto Tapipay al target de tu app.

Xcode embebe el framework sin pasos extra.

Package.swift

dependencies: [
    .package(
        url: "https://bitbucket.org/tapila/tapi-tapipay-ios-sdk.git",
        .upToNextMinor(from: "0.1.0")
    ),
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "Tapipay", package: "tapi-tapipay-ios-sdk"),
        ]
    ),
]

Mientras el SDK esté en versiones 0.x, usa Up to Next Minor Version (.upToNextMinor): recibes las correcciones (0.1.x) sin que una versión 0.2.0 cambie tu build sin aviso. El SDK solo se distribuye por Swift Package Manager (no hay CocoaPods ni Carthage).

No necesitas agregar permisos ni claves en tu Info.plist. Tapipay.present() presenta el widget de forma modal sobre la pantalla visible. Llámalo desde el hilo principal:

import Tapipay

do {
    try Tapipay.present(
        config: TapipayConfig(
            identifier: "CLI-00042",
            organization: "acme-corp",   // or companyCode: "MX-S-12345"
            environment: .homologation   // omit it in production
        )
    ) { event in
        switch event {
        case .paymentWindowOpened:
            break
        case .paymentSubmitted(let submission):
            // Submitted, not settled: show "processing" until the webhook arrives.
            showProcessing(submission.paymentId)
        case .paymentFailed:
            break                        // the user can retry inside the widget
        case .paymentCancelled:
            break
        case .closed:
            break                        // the user closed the widget
        case .failed(let error):
            showError(error)
        case .autopayLoaded, .autopayActivated, .autopayRemoved, .autopayError:
            break                        // only with view: .autopay
        @unknown default:
            break                        // required, see below
        }
    }
} catch {
    // Invalid configuration (TapipayError)
}

Por default el SDK presenta el widget desde la pantalla visible de tu app. Si quieres elegir desde dónde se presenta, pasa el parámetro from: con tu UIViewController. El widget no se cierra solo después de un pago. Ciérralo tú cuando lo necesites:

Tapipay.dismiss()
// or, if you need to chain something:
Tapipay.dismiss(animated: true) {
    // the widget is closed
}

dismiss() no emite .closed (tú ya sabes que lo cerraste) y no hace nada si no hay un widget abierto.

Botón de SwiftUI (opcional)

TapipayButton es un botón de SwiftUI que abre el widget al tocarlo:

import SwiftUI
import Tapipay

struct PaymentView: View {
    let config = TapipayConfig(identifier: "CLI-00042", organization: "acme-corp")

    var body: some View {
        TapipayButton(title: "Pay my bill", config: config) { event in
            print(event)
        }
        .buttonStyle(.borderedProminent)
    }
}

Si la configuración es inválida, el botón no lanza un error: te lo entrega como evento .failed. Si pasas onClick, el botón no abre el widget y te delega el toque.

Opciones de `TapipayConfig` en iOS

Opción	Tipo	Requerido	Default	Descripción
`identifier`	`String`	Sí		Identificador del usuario final.
`organization`	`String?`	Sí*	`nil`	`slug` de tu empresa. *Requerido salvo que pases `companyCode`.
`companyCode`	`String?`	Sí*	`nil`	Código de empresa. *Alternativa a `organization`; si pasas las dos, esta gana.
`view`	`TapipayViewMode`	No	`.payments`	`.payments` monta la vista de pagos; `.autopay`, la gestión de adhesiones.
`environment`	`TapipayEnvironment`	No	`.production`	`.production` o `.homologation`.
`externalRequestId`	`String?`	No	`nil`	Deuda a preseleccionar.
`selectionStrategy`	`TapipaySelectionStrategy?`	No	`nil`	`.oldestCreated` elige la deuda pendiente más antigua. Solo en `.payments`.
`appearance`	`TapipayAppearance`	No	`TapipayAppearance()`	Barra de navegación nativa del widget. Ver Apariencia.

Eventos en iOS

Evento	Cuándo llega
`.paymentWindowOpened`	Se abrió la ventana de pago del proveedor.
`.paymentSubmitted(TapipayPaymentSubmission)`	El usuario envió el pago. Trae `paymentId`, `status` (`.pending` o `.succeeded`) y `data`. No es la acreditación.
`.paymentFailed(TapipayPaymentFailure)`	El pago fue rechazado (`.failed`) o quedó pendiente de una acción (`.requiresAction`). El usuario sigue en el widget y puede reintentar.
`.paymentCancelled`	El usuario cerró la ventana de pago sin completar el flujo.
`.closed`	El usuario cerró el widget (botón Cerrar o deslizando la hoja). No llega cuando lo cierras con `Tapipay.dismiss()`.
`.failed(TapipayError)`	El widget no pudo cargar.
`.autopayLoaded`, `.autopayActivated`, `.autopayRemoved`, `.autopayError`	Eventos de la gestión de adhesiones.

Incluye siempre @unknown default en tu switch. En versiones nuevas del SDK pueden sumarse eventos: sin @unknown default, si llega un evento que tu app no conoce, la app se cierra con un error.

Errores de configuración

Tapipay.present() valida la configuración antes de abrir el widget y lanza un TapipayError:

Error	Causa
`.missingIdentifier`	`identifier` vacío.
`.invalidIdentifier`	`identifier` contiene `/` o `\`, o es `.` o `..`.
`.missingTarget`	No pasaste `organization` ni `companyCode`.
`.invalidTarget`	`organization` o `companyCode` contienen `/` o `\`, o son `.` o `..`.
`.selectionStrategyNotSupported`	Usaste `selectionStrategy` con `view: .autopay`.
`.noPresenterAvailable`	No hay una pantalla visible desde donde presentar el widget. Pasa `from:`.

Apariencia en iOS

Opción	Tipo	Default	Descripción
`navigationTitle`	`String`	”Pago”	Título de la barra de navegación.
`closeButtonTitle`	`String`	”Cerrar”	Texto del botón de cierre.
`tint`	`Color?`	tint de tu app	Color de los controles nativos (también tiñe el `TapipayButton`).
`backgroundColor`	`Color?`	sistema	Color de fondo mientras carga el widget.
`showsLoadingIndicator`	`Bool`	`true`	Muestra un indicador mientras carga el widget.
`showsNavigationBar`	`Bool`	`true`	Con `false`, el widget se muestra sin barra y se cierra deslizando la hoja.

Gestión de adhesiones

Con view = TapipayView.AUTOPAY (Android) o view: .autopay (iOS), el SDK monta la gestión de adhesiones: tu usuario ve sus medios adheridos, adhiere uno nuevo o desadhiere uno existente.

Android
iOS

Tapipay.present(
    context = this,
    config = TapipayConfig(
        identifier = "CLI-00042",
        organization = "acme-corp",
        view = TapipayView.AUTOPAY,
    ),
) { event ->
    when (event) {
        is TapipayEvent.AutopayLoaded -> updateCounter(event.count)
        is TapipayEvent.AutopayActivated -> Unit
        is TapipayEvent.AutopayRemoved -> Unit
        is TapipayEvent.AutopayError -> Unit
        TapipayEvent.Dismissed -> Unit
        is TapipayEvent.LoadFailed -> Unit
        else -> Unit
    }
}

try Tapipay.present(
    config: TapipayConfig(
        identifier: "CLI-00042",
        organization: "acme-corp",
        view: .autopay
    )
) { event in
    switch event {
    case .autopayLoaded(let loaded):
        updateCounter(loaded.count)
    case .autopayActivated, .autopayRemoved, .autopayError:
        break
    case .closed, .failed:
        break
    default:
        break
    }
}

Evento	Cuándo llega
`AutopayLoaded` / `.autopayLoaded`	Cargaron las adhesiones activas, y cada vez que el conjunto cambia. Trae `count`, `mediaTypes` y `adhesions`.
`AutopayActivated` / `.autopayActivated`	Se registró una adhesión nueva.
`AutopayRemoved` / `.autopayRemoved`	El usuario desadhirió un medio con éxito.
`AutopayError` / `.autopayError`	Falló la carga (`LOAD` / `.load`) o la desadhesión (`REMOVE` / `.remove`). Con `UNAVAILABLE` / `.unavailable` no es un fallo: tu organización no tiene la gestión de adhesiones habilitada.

Igual que en web, los eventos de adhesiones solo exponen el tipo de medio, los últimos 4 dígitos y un id opaco. Nunca viajan datos del titular ni el número de cuenta o tarjeta completos.

Entorno de homologación

Usa homologación mientras desarrollas y pruebas tu integración, y quita el parámetro (o usa producción) antes de publicar tu app.

Plataforma	Homologación	Producción (default)
Android	`TapipayEnvironment.HOMO`	`TapipayEnvironment.PRODUCTION`
iOS	`.homologation`	`.production`

Entorno	Origen del widget
Producción	`https://app.tapipay.la`
Homologación	`https://homo.tapipay.la`

Después del pago

El widget no se cierra solo cuando el usuario envía el pago: muestra una pantalla de “pago enviado” y queda abierto hasta que alguien lo cierre.

Evento	Qué te recomendamos hacer
`PaymentSubmitted` / `.paymentSubmitted`	Espera 1.5 a 2 segundos para que el usuario vea la confirmación y cierra con `Tapipay.dismiss()`, o reemplázalo por tu propia pantalla de “pago en proceso”. Muestra el pago como pendiente hasta que llegue el webhook.
`PaymentFailed` / `.paymentFailed`	No cierres el widget: el usuario puede reintentar ahí mismo.

Enlaces externos

El widget siempre se abre dentro de tu app. Si el usuario toca un enlace a otro sitio, se abre en el navegador; los enlaces tel:, mailto: o a otras apps se abren con la app correspondiente del sistema.

Próximamente

Canal bidireccional entre tu app y el SDK. Estamos desarrollando un canal de comunicación en los dos sentidos entre tu app y el SDK. Con él vamos a sumar nuevas funcionalidades a los SDK de TapiPay. Te avisaremos en las Novedades cuando esté disponible.

Empieza aquí

Novedades

Conceptos

Recursos

Portal de pagos

Webhooks

SDK para apps móviles

Android

iOS

Cómo funciona

Requisitos

Android

1. Agrega el repositorio de TapiPay

2. Agrega la dependencia

3. Abre el widget

4. Cierra el widget

Botón de Compose (opcional)

Opciones de `TapipayConfig`

Eventos en Android

Apariencia en Android

Buenas prácticas en Android

iOS

1. Agrega el paquete

2. Abre el widget

3. Cierra el widget

Botón de SwiftUI (opcional)

Opciones de `TapipayConfig` en iOS

Eventos en iOS

Errores de configuración

Apariencia en iOS

Gestión de adhesiones

Entorno de homologación

Después del pago

Enlaces externos

Próximamente

Android

iOS

​Cómo funciona

​Requisitos

​Android

​1. Agrega el repositorio de TapiPay

​2. Agrega la dependencia

​3. Abre el widget

​4. Cierra el widget

​Botón de Compose (opcional)

​Opciones de TapipayConfig

​Eventos en Android

​Apariencia en Android

​Buenas prácticas en Android

​iOS

​1. Agrega el paquete

​2. Abre el widget

​3. Cierra el widget

​Botón de SwiftUI (opcional)

​Opciones de TapipayConfig en iOS

​Eventos en iOS

​Errores de configuración

​Apariencia en iOS

​Gestión de adhesiones

​Entorno de homologación

​Después del pago

​Enlaces externos

​Próximamente

Cómo funciona

Requisitos

Android

1. Agrega el repositorio de TapiPay

2. Agrega la dependencia

3. Abre el widget

4. Cierra el widget

Botón de Compose (opcional)

Opciones de `TapipayConfig`

Eventos en Android

Apariencia en Android

Buenas prácticas en Android

iOS

1. Agrega el paquete

2. Abre el widget

3. Cierra el widget

Botón de SwiftUI (opcional)

Opciones de `TapipayConfig` en iOS

Eventos en iOS

Errores de configuración

Apariencia en iOS

Gestión de adhesiones

Entorno de homologación

Después del pago

Enlaces externos

Próximamente