Mobile apps SDK

The TapiPay native SDK opens the payment widget inside your Android or iOS app, on a screen owned by the SDK, and tells you through events what the user is doing. It is the mobile counterpart of the payment methods SDK: it mounts the same views (payments and autopay management) and uses the same data to identify your company and your user.

Android

Kotlin, Jetpack Compose or Views. Installed with Gradle.

iOS

Swift, SwiftUI or UIKit. Installed with Swift Package Manager.

How it works

Your app calls Tapipay.present(...) (or shows the SDK’s TapipayButton) with your user’s identifier and your company’s.
The SDK opens the TapiPay widget on a native screen, on top of your app.
While the user pays or manages their autopay enrollments, the SDK delivers events to a callback.
Your app closes the widget when it needs to, or the user closes it with the Close button or the back gesture.

No SDK event confirms a payment. When PaymentSubmitted (Android) or .paymentSubmitted (iOS) arrives, the user submitted the payment, but it is not settled yet. The real status reaches your backend through the payment notification.

Requirements

	Android	iOS
Minimum OS version	Android 8.0 (`minSdk` 26)	iOS 16
Language	Kotlin	Swift
Tooling	JDK 17 or later to build	Xcode 26 or later
Distribution	TapiPay Maven repository	Swift Package Manager
Current SDK version	`0.1.0`	`0.1.0`

On both platforms you need:

Your end user’s identifier (identifier), the same one you send when you create the debt.
Your company alias (organization) or your company code (companyCode). They work the same as in the web SDK: see Identify your company.

Android

1. Add the TapiPay repository

The SDK is distributed through a TapiPay Maven repository. Add it to your project’s settings.gradle.kts:

settings.gradle.kts

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

2. Add the dependency

In your app module’s build.gradle.kts:

build.gradle.kts

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

The artifact is named button for compatibility, but it contains the full SDK: the widget screen, the events and the optional button.

You do not need to change your AndroidManifest.xml: the SDK already declares the INTERNET permission and its own screen. You do not need ProGuard or R8 rules either: the SDK ships its own. The SDK brings Jetpack Compose and Material 3 as dependencies. If your app uses Views (XML), you can still open the widget with Tapipay.present(); only TapipayButton requires Compose. Call Tapipay.present() from any Context (ideally an 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() throws IllegalArgumentException if the configuration is invalid: identifier is missing, you pass neither organization nor companyCode, or you use selectionStrategy with the autopay view. The event callback is always invoked on the main thread. The widget does not close by itself after a payment. Close it when you need to:

Tapipay.dismiss()

dismiss() does not emit any event (you already know you closed it) and does nothing if no widget is open. You can call it from any thread.

Compose button (optional)

If your app uses Jetpack Compose, TapipayButton renders a Material 3 button that opens the widget when tapped:

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) },
)

It takes colors and typography from your MaterialTheme. If you pass onClick, the button does not open the widget and hands the tap to you.

`TapipayConfig` options

Option	Type	Required	Default	Description
`identifier`	`String`	Yes		End user identifier.
`organization`	`String?`	Yes*	`null`	Your company `slug`. *Required unless you pass `companyCode`.
`companyCode`	`String?`	Yes*	`null`	Company code. *Alternative to `organization`; if you pass both, this one wins.
`view`	`TapipayView`	No	`PAYMENTS`	`PAYMENTS` mounts the payments view; `AUTOPAY`, autopay management.
`environment`	`TapipayEnvironment`	No	`PRODUCTION`	`PRODUCTION` or `HOMO` (staging).
`externalRequestId`	`String?`	No	`null`	Debt to preselect.
`selectionStrategy`	`TapipaySelectionStrategy?`	No	`null`	`OLDEST_CREATED` picks the oldest pending debt. `PAYMENTS` only.
`appearance`	`TapipayAppearance`	No	your app theme	Native top bar of the widget. See Appearance.

Events on Android

TapipayEvent is a sealed interface:

Event	When it arrives
`PaymentWindowOpened`	The provider’s payment window opened.
`PaymentSubmitted(paymentId, status, data)`	The user submitted the payment. `status` is `PENDING` or `SUCCEEDED`. It is not the settlement.
`PaymentFailed(paymentId, status, reason)`	The payment was declined or is waiting for an action (for example, 3DS). The user stays in the widget and can retry.
`PaymentCancelled`	The user closed the payment window without completing the flow.
`Dismissed`	The user closed the widget (Close button or back). It is the last event of the session. It does not arrive when you close it with `Tapipay.dismiss()`.
`LoadFailed(reason)`	The widget could not load (no network, server error).
`AutopayLoaded`, `AutopayActivated`, `AutopayRemoved`, `AutopayError`	Autopay management events.

Always include an else -> branch in your when. New SDK versions can add events: without else, your code stops compiling or silently ignores the event. Kotlin may flag the else as redundant; keep it anyway.

Appearance on Android

TapipayAppearance configures the native top bar that wraps the widget. If you pass nothing, it uses your MaterialTheme colors.

Option	Type	Default	Description
`title`	`String?`	”Pagar”	Bar title.
`showToolbar`	`Boolean`	`true`	With `false`, the widget takes the whole screen and closes with the system back button.
`closeText`	`String?`	”Cerrar”	Close button text.
`closeContentDescription`	`String?`	`closeText`	Text TalkBack reads for the close button.
`toolbarContainerColorArgb`	`Int?`	theme	Bar background color (ARGB).
`toolbarContentColorArgb`	`Int?`	theme	Title and close button color (ARGB).

You can also redefine the default texts in your app with the tapipay_button_text, tapipay_checkout_title, tapipay_checkout_close and tapipay_checkout_load_failed resources.

Android best practices

One widget at a time. If you call present() while a widget is already open (for example, on a double tap), the call is ignored.
Do not capture the Activity in the callback. The SDK keeps the callback while the widget is open. Forward events to a ViewModel or check the Lifecycle before touching the UI.
Rotation and dark mode do not recreate the widget screen. If Android destroys the screen due to low memory, the widget reloads and the user has to fill in the form again.

iOS

1. Add the package

The SDK is distributed through Swift Package Manager from this repository:

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

Xcode
Package.swift

Open File → Add Package Dependencies…
Paste the repository URL.
Under Dependency Rule, choose Up to Next Minor Version from 0.1.0.
Add the Tapipay product to your app target.

Xcode embeds the framework with no extra steps.

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"),
        ]
    ),
]

While the SDK is on 0.x versions, use Up to Next Minor Version (.upToNextMinor): you get fixes (0.1.x) without a 0.2.0 release changing your build unexpectedly. The SDK is only distributed through Swift Package Manager (no CocoaPods or Carthage).

You do not need to add permissions or keys to your Info.plist. Tapipay.present() presents the widget modally over the visible screen. Call it from the main thread:

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)
}

By default the SDK presents the widget from your app’s visible screen. To choose where it is presented from, pass the from: parameter with your UIViewController. The widget does not close by itself after a payment. Close it when you need to:

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

dismiss() does not emit .closed (you already know you closed it) and does nothing if no widget is open.

SwiftUI button (optional)

TapipayButton is a SwiftUI button that opens the widget when tapped:

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)
    }
}

If the configuration is invalid, the button does not throw: it delivers the error as a .failed event. If you pass onClick, the button does not open the widget and hands the tap to you.

`TapipayConfig` options on iOS

Option	Type	Required	Default	Description
`identifier`	`String`	Yes		End user identifier.
`organization`	`String?`	Yes*	`nil`	Your company `slug`. *Required unless you pass `companyCode`.
`companyCode`	`String?`	Yes*	`nil`	Company code. *Alternative to `organization`; if you pass both, this one wins.
`view`	`TapipayViewMode`	No	`.payments`	`.payments` mounts the payments view; `.autopay`, autopay management.
`environment`	`TapipayEnvironment`	No	`.production`	`.production` or `.homologation`.
`externalRequestId`	`String?`	No	`nil`	Debt to preselect.
`selectionStrategy`	`TapipaySelectionStrategy?`	No	`nil`	`.oldestCreated` picks the oldest pending debt. `.payments` only.
`appearance`	`TapipayAppearance`	No	`TapipayAppearance()`	Native navigation bar of the widget. See Appearance.

Events on iOS

Event	When it arrives
`.paymentWindowOpened`	The provider’s payment window opened.
`.paymentSubmitted(TapipayPaymentSubmission)`	The user submitted the payment. Carries `paymentId`, `status` (`.pending` or `.succeeded`) and `data`. It is not the settlement.
`.paymentFailed(TapipayPaymentFailure)`	The payment was declined (`.failed`) or is waiting for an action (`.requiresAction`). The user stays in the widget and can retry.
`.paymentCancelled`	The user closed the payment window without completing the flow.
`.closed`	The user closed the widget (Close button or swiping the sheet down). It does not arrive when you close it with `Tapipay.dismiss()`.
`.failed(TapipayError)`	The widget could not load.
`.autopayLoaded`, `.autopayActivated`, `.autopayRemoved`, `.autopayError`	Autopay management events.

Always include @unknown default in your switch. New SDK versions can add events: without @unknown default, if an event your app does not know arrives, the app crashes.

Configuration errors

Tapipay.present() validates the configuration before opening the widget and throws a TapipayError:

Error	Cause
`.missingIdentifier`	Empty `identifier`.
`.invalidIdentifier`	`identifier` contains `/` or `\`, or is `.` or `..`.
`.missingTarget`	You passed neither `organization` nor `companyCode`.
`.invalidTarget`	`organization` or `companyCode` contain `/` or `\`, or are `.` or `..`.
`.selectionStrategyNotSupported`	You used `selectionStrategy` with `view: .autopay`.
`.noPresenterAvailable`	There is no visible screen to present the widget from. Pass `from:`.

Appearance on iOS

Option	Type	Default	Description
`navigationTitle`	`String`	”Pago”	Navigation bar title.
`closeButtonTitle`	`String`	”Cerrar”	Close button text.
`tint`	`Color?`	your app tint	Color of the native controls (it also tints `TapipayButton`).
`backgroundColor`	`Color?`	system	Background color while the widget loads.
`showsLoadingIndicator`	`Bool`	`true`	Shows an indicator while the widget loads.
`showsNavigationBar`	`Bool`	`true`	With `false`, the widget is shown without a bar and closes by swiping the sheet down.

Autopay management

With view = TapipayView.AUTOPAY (Android) or view: .autopay (iOS), the SDK mounts autopay management: your user sees their enrolled payment methods, enrolls a new one or removes an existing one.

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
    }
}

Event	When it arrives
`AutopayLoaded` / `.autopayLoaded`	Active enrollments finished loading, and every time the set changes. Carries `count`, `mediaTypes` and `adhesions`.
`AutopayActivated` / `.autopayActivated`	A new enrollment was registered.
`AutopayRemoved` / `.autopayRemoved`	The user removed a payment method successfully.
`AutopayError` / `.autopayError`	Loading (`LOAD` / `.load`) or removal (`REMOVE` / `.remove`) failed. `UNAVAILABLE` / `.unavailable` is not a failure: your organization does not have autopay management enabled.

As on the web, autopay events only expose the payment method type, the last 4 digits and an opaque id. Account holder data and full account or card numbers never travel.

Staging environment

Use staging while you build and test your integration, and remove the parameter (or use production) before you publish your app.

Platform	Staging	Production (default)
Android	`TapipayEnvironment.HOMO`	`TapipayEnvironment.PRODUCTION`
iOS	`.homologation`	`.production`

Environment	Widget origin
Production	`https://app.tapipay.la`
Staging	`https://homo.tapipay.la`

After the payment

The widget does not close by itself when the user submits the payment: it shows a “payment submitted” screen and stays open until someone closes it.

Event	What we recommend
`PaymentSubmitted` / `.paymentSubmitted`	Wait 1.5 to 2 seconds so the user sees the confirmation and close with `Tapipay.dismiss()`, or replace it with your own “payment in progress” screen. Show the payment as pending until the webhook arrives.
`PaymentFailed` / `.paymentFailed`	Do not close the widget: the user can retry right there.

External links

The widget always opens inside your app. If the user taps a link to another site, it opens in the browser; tel:, mailto: or other app links open with the matching system app.

Coming soon

Two-way channel between your app and the SDK. We are building a two-way communication channel between your app and the SDK. It will bring new features to the TapiPay SDKs. We will let you know in What’s new when it is available.

Get started

What's new

Concepts

Resources

Payment portal

Webhooks

Mobile apps SDK

Android

iOS

How it works

Requirements

Android

1. Add the TapiPay repository

2. Add the dependency

3. Open the widget

4. Close the widget

Compose button (optional)

`TapipayConfig` options

Events on Android

Appearance on Android

Android best practices

iOS

1. Add the package

2. Open the widget

3. Close the widget

SwiftUI button (optional)

`TapipayConfig` options on iOS

Events on iOS

Configuration errors

Appearance on iOS

Autopay management

Staging environment

After the payment

External links

Coming soon

Android

iOS

​How it works

​Requirements

​Android

​1. Add the TapiPay repository

​2. Add the dependency

​3. Open the widget

​4. Close the widget

​Compose button (optional)

​TapipayConfig options

​Events on Android

​Appearance on Android

​Android best practices

​iOS

​1. Add the package

​2. Open the widget

​3. Close the widget

​SwiftUI button (optional)

​TapipayConfig options on iOS

​Events on iOS

​Configuration errors

​Appearance on iOS

​Autopay management

​Staging environment

​After the payment

​External links

​Coming soon

How it works

Requirements

Android

1. Add the TapiPay repository

2. Add the dependency

3. Open the widget

4. Close the widget

Compose button (optional)

`TapipayConfig` options

Events on Android

Appearance on Android

Android best practices

iOS

1. Add the package

2. Open the widget

3. Close the widget

SwiftUI button (optional)

`TapipayConfig` options on iOS

Events on iOS

Configuration errors

Appearance on iOS

Autopay management

Staging environment

After the payment

External links

Coming soon