Tapaya Terminal App

Nehmen Sie kontaktlose Kartenzahlungen in Ihrer Android-App an, indem Sie die Interaktion mit der Karte an die Plugin-App Tapaya Terminal übergeben. Ihre App behält die Kontrolle über den Verkauf; das Plugin übernimmt das Vorhalten der Karte per NFC, die PIN-Eingabe und die Kartenverarbeitung, und das Ergebnis fließt anschließend über den Event-Stream von Accept.payments.pay() zurück.

Verwenden Sie diese Integration, wenn Sie Tap to Pay anbieten möchten, ohne einen Zahlungsabwickler in Ihre eigene App einzubetten. Ist für Ihre Plattform stattdessen eingebettetes Tap to Pay freigeschaltet, lesen Sie den Leitfaden Embedded Tap to Pay.

Integrationsoptionen

Zuerst wird der Weg über das SDK beschrieben; die Spezifikation des Deeplinks finden Sie unter Integration ohne SDK.

So funktioniert es

1. Ihre App startet eine Zahlung mit Accept.payments.pay(amount, currency).
2. Das SDK registriert die Zahlung beim Tapaya-Backend und startet das Tapaya-Terminal-Plugin auf demselben Gerät.
3. Der Kunde hält seine Karte oder sein Telefon an den Bildschirm von Tapaya Terminal.
4. Tapaya Terminal schließt die Zahlung mit dem Tapaya-Backend ab.
5. Das SDK beobachtet die Zahlung, bis sie einen Endzustand erreicht, und gibt PaymentEvent.Result mit einem PayResult aus. Kann die Zahlung überhaupt nicht erstellt werden, gibt es stattdessen PaymentEvent.CreationFailed aus, in der Regel innerhalb einer Sekunde.

Voraussetzungen

• Das Tapaya-Terminal-Plugin ist auf dem Gerät installiert und für Ihren Händler aktiviert (siehe Terminal installieren und aktivieren).
• Ein Gerät mit NFC und Android 11 (API 30) oder neuer.
• Das Accept SDK ist installiert und initialisiert, und der Händler ist angemeldet.
• Die Standortberechtigung (ACCESS_FINE_LOCATION) wurde Ihrer App zur Laufzeit erteilt.

Terminal installieren und aktivieren

Die Aktivierung erfolgt einmal pro Gerät. Sie verknüpft das Tapaya-Terminal-Plugin mit demselben Händlerkonto, bei dem Ihre App angemeldet ist.

if (!Accept.plugin.isInstalled()) {
    // Opens the store listing so the user can install Tapaya Terminal
    Accept.plugin.install()
    return
}

// suspend; launches the plugin's activation flow and waits for the outcome
when (val result = Accept.plugin.activateTerminal()) {
    ActivateTerminalResult.Success -> { /* device linked, ready to take payments */ }
    ActivateTerminalResult.Canceled -> { /* user backed out */ }
    is ActivateTerminalResult.Failed -> result.reason // ActivateTerminalFailureReason
}

ActivateTerminalFailureReason ist einer der Werte INVALID_INTENT, HANDOVER_FAILED, CONFIRM_FAILED, MERCHANT_NOT_ONBOARDED oder UNKNOWN.

activateTerminal() wirft außerdem NoTidsAvailableForMerchant, wenn dem Händler kein nicht zugewiesenes Terminal (TID) mehr zur Aktivierung bleibt, und zwar getrennt von den oben genannten Ergebnissen ActivateTerminalResult.Failed. Umschließen Sie den Aufruf mit try-catch, wenn Sie diesen Fall gesondert anzeigen möchten, zum Beispiel indem Sie den Händler auffordern, eine TID freizugeben oder eine weitere anzufordern.

Nach Plugin-Updates suchen

Accept.plugin.updateInfo() meldet, ob auf Google Play ein neuerer Build des Tapaya-Terminal-Plugins verfügbar ist, sodass Sie den Händler zum Aktualisieren auffordern können, bevor eine Zahlung auf eine Versionslücke trifft.

when (val info = Accept.plugin.updateInfo()) {
    PluginUpdateInfo.UpToDate -> { /* nothing to do */ }
    is PluginUpdateInfo.UpdateAvailable -> promptUpdate(info.priority) // Int, higher is more urgent
    PluginUpdateInfo.Unknown -> { /* not installed, or an older plugin build that predates this check */ }
}

Zahlung erstellen

Beträge werden immer in der kleinsten Einheit der Währung angegeben: Heller für CZK, Cent für EUR. 1500 mit der Währung "CZK" belastet 15,00 Kč. Währungen sind ISO-4217-Codes.

pay() gibt einen Flow<PaymentEvent> zurück; sammeln Sie ihn, um den Fortschritt und das endgültige Ergebnis zu verfolgen. Die Methode wirft nie eine Exception; Fehler zeigen sich als PaymentEvent.CreationFailed.

Accept.payments.pay(amount = 1500, currency = "CZK") // 15.00 Kč
    .collect { event ->
        when (event) {
            PaymentEvent.Creating -> { /* registering the payment */ }
            is PaymentEvent.Created -> { /* backend payment created: event.paymentToken */ }
            PaymentEvent.Launched -> { /* Tapaya Terminal is in the foreground */ }
            is PaymentEvent.Result -> when (val r = event.payResult) {
                is PayResult.Success -> showReceipt(r.paymentToken, r.authCode)
                is PayResult.Declined -> showDeclined(r.metadata)
                is PayResult.Canceled -> showCancelled(r.metadata)
                is PayResult.Failed -> showUnexpected(r.reason) // PayFailureReason
            }
            is PaymentEvent.CreationFailed -> handleError(event.cause) // AcceptException
        }
    }

Parameter:

Während die Zahlung läuft, ist das Tapaya-Terminal-Plugin im Vordergrund. Ihre App wird automatisch fortgesetzt, sobald die Zahlung abgeschlossen ist. Um eine unterbrochene Zahlung fortzusetzen, übergeben Sie ihr paymentToken erneut an pay(amount, currency, paymentToken).

Währung wählen

pay() belastet den Betrag in der übergebenen currency, angegeben als ISO-4217-Code in Großbuchstaben, mit amount in der kleinsten Einheit dieser Währung. Unter Unterstützte Währungen finden Sie alle Währungen, die Tapaya unterstützt, ein Händler ist jedoch meist nur für einige davon freigeschaltet.

Rufen Sie Accept.merchant.availableCurrencies() auf, um die ISO-4217-Codes zu erhalten, für die der Händler freigeschaltet ist. Eine Zahlung in jeder anderen Währung schlägt mit CurrencyNotAvailableForMerchant fehl.

Jede Währung hat außerdem einen Mindestbetrag, der plattformweit durchgesetzt wird. Die aktuellen Mindestbeträge rufen Sie mit Accept.sdk.minimumAmounts() ab, das eine List<MinimumAmount> zurückgibt (currency: String, amount: Long, in der kleinsten Einheit der Währung). Ein Aufruf von pay() unterhalb dieses Mindestbetrags schlägt mit PaymentEvent.CreationFailed(AmountBelowMinimum(minimum, currency)) fehl. Die vollständige Liste der Exceptions finden Sie unter Fehlerbehandlung.

Belegbildschirm konfigurieren

receiptConfig legt fest, was das Tapaya-Terminal-Plugin dem Zahlenden nach einer genehmigten Zahlung anzeigt, wie lange es auf dem Bildschirm bleibt und ob gedruckt wird. Auf abgelehnte, stornierte oder auf Stornierung wartende Ergebnisse hat es keinen Einfluss; diese zeigen unabhängig von dieser Einstellung immer ihren eigenen Ergebnisbildschirm.

Legen Sie einmalig mit Accept.payments.setOptions() einen geräteweiten Standard fest und überschreiben Sie ihn für eine einzelne Zahlung über pay(..., receiptConfig = ...). Solange setOptions() nicht aufgerufen wurde, ist der Standard Show mit QR-Beleg, manuellem Schließen und Druck auf Anforderung, was dem eigenen Fallback des Plugins entspricht.

// Set a default, e.g. once at app startup
Accept.payments.setOptions(
    receiptConfig = PaymentReceiptConfig.Show(
        showQrCodeReceipt = true,
        dismissBehavior = DismissBehavior.Delayed(30.seconds),
        printBehavior = ReceiptPrintBehavior.Automatic,
    ),
)

// Override it for a single payment
Accept.payments.pay(
    amount = 1500,
    currency = "CZK",
    receiptConfig = PaymentReceiptConfig.DismissImmediately,
)

NFC-Animation positionieren

nfcPosition ist ein Hinweis, der dem Tapaya-Terminal-Plugin mitteilt, wo sich die NFC-Antenne dieses Geräts befindet, damit es die Animation „Hier vorhalten“ richtig platzieren kann. Das Plugin ermittelt die Position der Antenne zunächst selbst (Live-Erkennung über die Plattform, dann eine mitgelieferte Gerätedatenbank, dann alles, was der Händler direkt im Plugin konfiguriert hat); geben Sie diesen Wert nur an, um diese Ermittlung zu überschreiben, zum Beispiel bei einem Gerät, das das Plugin nicht erkennen kann oder das in seiner Datenbank falsch hinterlegt ist.

Legen Sie mit Accept.payments.setOptions(nfcPosition = ...) einen geräteweiten Standard fest oder überschreiben Sie ihn pro Aufruf über pay(..., nfcPosition = ...). setOptions() ändert nur die übergebenen Optionen, daher stört setOptions(nfcPosition = ...) allein keinen zuvor gesetzten Standard für receiptConfig und umgekehrt.

Transaktions-Timeout festlegen

transactionTimeout legt fest, wie lange das Tapaya-Terminal-Plugin darauf wartet, dass der Kunde seine Karte vorhält, bevor es aufgibt. Es akzeptiert jede Duration von null bis 120 Sekunden; alles außerhalb dieses Bereichs zeigt sich als TransactionTimeoutOutOfRange(transactionTimeout) über PaymentEvent.CreationFailed, da pay() nie synchron eine Exception wirft.

Accept.payments.pay(
    amount = 1500,
    currency = "CZK",
    transactionTimeout = 90.seconds,
)

Belassen Sie den Standardwert null, um den eigenen Fallback der Begleit-App von etwa 60 Sekunden zu verwenden, oder legen Sie mit Accept.payments.setOptions(transactionTimeout = ...) einen geräteweiten Standard fest.

Display auswählen

Bei einem zweiseitigen Gerät („double-sided“) ist ein Panel dem Händler zugewandt und ein zweites, kundenseitiges Panel dem Zahlenden. Accept.displays meldet, welche Displays das Gerät gerade hat, und die Option display teilt dem Plugin mit, auf welchem Panel es seine Zahlungsoberfläche ausführen soll.

if (Accept.displays.isDualScreen) {
    val customerPanel = Accept.displays.customerFacing() // AcceptDisplay?, null on single-screen devices
}

Accept.payments.pay(
    amount = 1500,
    currency = "CZK",
    display = PaymentDisplay.CustomerFacing,
)

Ein Ziel, das nicht umgesetzt werden kann, zum Beispiel CustomerFacing auf einem Gerät mit nur einem Bildschirm, fällt stillschweigend auf Default zurück. Legen Sie mit Accept.payments.setOptions(display = ...) einen geräteweiten Standard fest oder überschreiben Sie ihn pro Aufruf über pay(..., display = ...).

Die Beispiel-App :dualscreen zeigt einen vollständigen Bezahlvorgang auf zwei Panels: Der Händler arbeitet auf dem primären Panel, während PaymentDisplay.CustomerFacing die Zahlungsoberfläche des Plugins auf den Bildschirm des Kunden bringt.

Zahlungsergebnis

Das abschließende PaymentEvent.Result enthält ein PayResult. Jede Variante enthält metadata und gibt damit zurück, was Sie an pay() übergeben haben, sofern das Plugin es zurückliefert (kann null sein):

PayFailureReason ist einer der Werte INVALID_INTENT, NOT_ACTIVATED, TERMINAL_INIT_FAILED, PAYMENT_SETUP_FAILED, PLUGIN_UNAVAILABLE oder UNKNOWN.

Belegdaten auslesen

Success und Declined enthalten optional receiptDetails: ReceiptDetails? mit strukturierten, vom Terminal gemeldeten Daten für den Kartenbeleg. Sie sind für Aufrufer gedacht, die ihren eigenen offiziellen Kartenbeleg drucken, statt sich allein auf die gehostete Seite unter PaymentStatus.receiptUrl zu verlassen.

Jedes Feld ist optional und ohne Gewähr; ein Aufrufer muss damit rechnen, dass jedes davon, oder receiptDetails selbst, fehlt.

Zahlungsdetails auslesen

PayResult.Success liefert Ihnen das paymentToken. Den vollständigen Datensatz, einschließlich receiptUrl, angeforderter und abgerechneter Beträge sowie Zeitstempeln, rufen Sie mit Accept.payments.status() ab:

val status: PaymentStatus = Accept.payments.status(paymentToken)
status.state       // PENDING, SUCCESS, CANCELLED, REFUNDED, FAILED, ACTION_NEEDED
status.receiptUrl  // for your receipt UI

Eine laufende Zahlung stoppen Sie mit Accept.payments.cancel(paymentToken), das den resultierenden PaymentState zurückgibt.

Erstattung ausführen

Eine abgeschlossene Zahlung erstatten Sie mit Accept.payments.refund(paymentToken, reason), das ebenfalls den resultierenden PaymentState zurückgibt.

val state: PaymentState = Accept.payments.refund(paymentToken, RefundReason.CUSTOMER_REQUEST)

RefundReason ist einer der Werte CUSTOMER_REQUEST, DUPLICATE, FRAUDULENT oder EXPIRED_CHARGE.

Fehlerbehandlung

Eine Zahlung, die das Terminal erreicht, aber nicht erfolgreich ist, ist keine Exception; sie kommt als PaymentEvent.Result mit PayResult.Declined, Canceled oder Failed(reason) an. Fehler, die das Erstellen der Zahlung verhindern, kommen als PaymentEvent.CreationFailed(cause) an, wobei cause eine typisierte AcceptException ist. Die für diese Integration spezifischen Exceptions:

Accept.payments.status(), cancel() und refund() sind suspend-Funktionen und werfen diese Exceptions (statt Events auszugeben); umschließen Sie sie mit try-catch. status()/cancel()/refund() werfen außerdem PaymentNotFound für ein unbekanntes Token. Die vollständige Liste finden Sie unter Fehlerbehandlung.

Timeouts

Eine Kartenzahlung muss kurz nach ihrem Start am Terminal abgeschlossen werden. Hält der Kunde die Karte nie vor oder wird das Tapaya-Terminal-Plugin während der Zahlung geschlossen, endet die Zahlung als PayResult.Canceled oder PayResult.Failed, und die zugrunde liegende Zahlung wird serverseitig abgebrochen und nie abgeschlossen. Bestätigen Sie immer den Endzustand mit Accept.payments.status(), bevor Sie eine Zahlung als abgeschlossen behandeln.

Integration ohne SDK

Wenn Sie das Accept SDK nicht einbetten können (ein plattformübergreifendes Framework, eine schlanke POS-Shell, eine webbasierte Kasse), können Sie Tapaya Terminal direkt über einen Deeplink steuern. Dabei ändert sich die Aufgabenteilung: Sie erstellen die Zahlung über die Tapaya API, und Sie fragen ihren Status regelmäßig ab, um das Ergebnis zu erhalten; Tapaya Terminal übernimmt nur die Interaktion mit der Karte.

Der Ablauf:

1. Erstellen Sie über Ihr Backend eine Zahlung mit der Payments API und speichern Sie ihre paymentId.
2. Öffnen Sie Tapaya Terminal mit dieser paymentId über den Zahlungs-Deeplink.
3. Fragen Sie den Zahlungsstatus regelmäßig über die Payments API ab, bis er PENDING verlässt. Deeplinks haben keinen Rückkanal, daher ist die Abfrage die einzige verlässliche Quelle für das Ergebnis.

Deeplink-Schemata

Das Schema bestimmt, welcher Build von Tapaya Terminal den Link verarbeitet:

Lässt sich ein Link nicht auflösen, ist dieser Build von Tapaya Terminal nicht installiert.

Zahlungs-Deeplink

tapaya-accept://pay?paymentId=<paymentId>&amount=<amount>&currency=<ISO4217>

val uri = Uri.parse("tapaya-accept://pay?paymentId=$paymentId&amount=15&currency=CZK")
try {
    startActivity(Intent(Intent.ACTION_VIEW, uri).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
} catch (e: ActivityNotFoundException) {
    // Tapaya Terminal is not installed, send the user to Google Play
}

Login-Deeplink

Melden Sie einen Händler mit seinem merchantToken bei Tapaya Terminal an. Das ist die Händlerkennung, die Sie mit POST /merchant/auth/register festlegen:

tapaya-accept://login?token=<merchantToken>

Integration testen

1. Initialisieren Sie mit isProduction = false (Standard); Sandbox-Zahlungen bewegen nie echtes Geld.
2. Installieren Sie das Tapaya-Terminal-Plugin auf Ihrem Testgerät, melden Sie sich mit einem Sandbox-Händler an und aktivieren Sie es.
3. Führen Sie eine Zahlung über einen kleinen Betrag aus und prüfen Sie den Success-Ablauf von Anfang bis Ende, einschließlich Ihrer Beleganzeige.
4. Testen Sie die Fehlerpfade: Lehnen Sie eine Zahlung am Terminal ab, brechen Sie eine ab und starten Sie eine in einer nicht unterstützten Währung; Ihre Behandlung von PayResult/CreationFailed sollte jeden dieser Fälle abdecken.

Wenn Sie bereit sind, live zu gehen, setzen Sie in initialize den Wert isProduction = true und authentifizieren Sie sich mit Zugangsdaten für die Produktion. Der Zahlungscode ändert sich nicht.