Aplikácia Tapaya Terminal

Prijímajte bezkontaktné platby kartou zo svojej aplikácie pre Android tak, že prácu s kartou odovzdáte pluginovej aplikácii Tapaya Terminal. Predaj zostáva pod kontrolou vašej aplikácie; plugin zabezpečí priloženie karty cez NFC, zadanie PIN a spracovanie karty a výsledok sa potom vráti cez prúd udalostí Accept.payments.pay().

Túto integráciu použite, ak chcete Tap to Pay bez toho, aby ste do vlastnej aplikácie vkladali spracovateľa platieb. Ak má vaša platforma namiesto toho povolené vstavané Tap to Pay, prečítajte si sprievodcu Embedded Tap to Pay.

Možnosti integrácie

Najprv je popísaná cesta cez SDK; kontrakt deeplinku nájdete v časti Integrácia bez SDK.

Ako to funguje

1. Vaša aplikácia spustí platbu volaním Accept.payments.pay(amount, currency).
2. SDK zaregistruje platbu v backende Tapaya a spustí plugin Tapaya Terminal na tom istom zariadení.
3. Zákazník priloží kartu alebo telefón k obrazovke Tapaya Terminal.
4. Tapaya Terminal dokončí spracovanie platby s backendom Tapaya.
5. SDK sleduje platbu, kým nedosiahne konečný stav, a vyšle PaymentEvent.Result s PayResult. Ak platbu vôbec nemožno vytvoriť, vyšle namiesto toho PaymentEvent.CreationFailed, zvyčajne do jednej sekundy.

Predpoklady

• Plugin Tapaya Terminal nainštalovaný v zariadení a aktivovaný pre vášho obchodníka (pozrite Inštalácia a aktivácia terminálu).
• Zariadenie s NFC so systémom Android 11 (API 30) alebo novším.
• Accept SDK nainštalované a inicializované, s prihláseným obchodníkom.
• Oprávnenie na polohu (ACCESS_FINE_LOCATION) udelené vašej aplikácii počas behu.

Inštalácia a aktivácia terminálu

Aktiváciu vykonajte raz pre každé zariadenie. Aktivácia prepojí plugin Tapaya Terminal s tým istým účtom obchodníka, pod ktorým je prihlásená vaša aplikácia.

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 je jedna z hodnôt INVALID_INTENT, HANDOVER_FAILED, CONFIRM_FAILED, MERCHANT_NOT_ONBOARDED alebo UNKNOWN.

activateTerminal() navyše vyhadzuje NoTidsAvailableForMerchant, keď obchodníkovi nezostáva žiadny nepriradený terminál (TID) na aktiváciu, a to oddelene od vyššie uvedených výsledkov ActivateTerminalResult.Failed. Ak chcete tento prípad zobraziť osobitne, napríklad vyzvať obchodníka, aby uvoľnil alebo si vyžiadal ďalší TID, obaľte volanie do try-catch.

Kontrola aktualizácií pluginu

Accept.plugin.updateInfo() hlási, či je na Google Play k dispozícii novšie zostavenie pluginu Tapaya Terminal, takže môžete obchodníka vyzvať na aktualizáciu skôr, než platba narazí na rozdiel verzií.

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

Vytvorenie platby

Sumy sú vždy v najmenšej jednotke meny: haliere pre CZK, centy pre EUR. 1500 s menou "CZK" naúčtuje 15,00 Kč. Meny sa zadávajú ako kódy ISO 4217.

pay() vracia Flow<PaymentEvent>; zbierajte ho, aby ste sledovali priebeh a konečný výsledok. Nikdy nevyhadzuje výnimku; zlyhania sa prejavia ako 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
        }
    }

Parametre:

Počas platby je plugin Tapaya Terminal v popredí. Po dokončení platby sa vaša aplikácia automaticky vráti do popredia. Ak chcete obnoviť prerušenú platbu, odovzdajte jej paymentToken späť do pay(amount, currency, paymentToken).

Voľba meny

pay() účtuje v mene currency, ktorú odovzdáte ako kód ISO 4217 veľkými písmenami, so sumou amount v najmenšej jednotke tejto meny. Stránka Podporované meny uvádza všetky meny, ktoré Tapaya podporuje, no obchodník má zvyčajne povolené len niektoré z nich.

Kódy ISO 4217, ktoré má obchodník povolené, zistíte volaním Accept.merchant.availableCurrencies(). Platba v akejkoľvek inej mene zlyhá s CurrencyNotAvailableForMerchant.

Každá mena má tiež minimálnu sumu na zaplatenie, ktorá sa vynucuje v celej platforme. Aktuálne minimá načítate pomocou Accept.sdk.minimumAmounts(), ktoré vracia List<MinimumAmount> (currency: String, amount: Long, v najmenšej jednotke meny). Volanie pay() pod týmto minimom zlyhá s PaymentEvent.CreationFailed(AmountBelowMinimum(minimum, currency)). Úplný zoznam výnimiek nájdete v časti Spracovanie chýb.

Nastavenie obrazovky účtenky

receiptConfig určuje, čo plugin Tapaya Terminal zobrazí platiteľovi po schválenej platbe, ako dlho to zostane na obrazovke a či sa účtenka vytlačí. Nemá žiadny vplyv na zamietnuté a stornované platby ani na platby čakajúce na storno; tie vždy zobrazia vlastnú obrazovku výsledku bez ohľadu na toto nastavenie.

Predvolené nastavenie pre celé zariadenie nastavte raz pomocou Accept.payments.setOptions() a pre jednotlivú platbu ho prepíšte cez pay(..., receiptConfig = ...). Kým nezavoláte setOptions(), predvolená hodnota je Show s QR účtenkou, ručným zatvorením a tlačou na požiadanie, čo zodpovedá vlastnému záložnému nastaveniu pluginu.

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

Umiestnenie animácie priloženia cez NFC

nfcPosition je nápoveda, ktorá pluginu Tapaya Terminal oznamuje, kde má toto zariadenie anténu NFC, aby mohol správne umiestniť animáciu „priložte sem“. Plugin najprv určí polohu antény sám (živou detekciou platformy, potom z pribalenej databázy zariadení a nakoniec z čohokoľvek, čo obchodník nastavil priamo v plugine); túto hodnotu zadávajte len vtedy, keď chcete toto určenie prepísať, napríklad pri zariadení, ktoré plugin nedokáže rozpoznať alebo ho má vo svojej databáze nesprávne.

Predvolené nastavenie pre celé zariadenie nastavte pomocou Accept.payments.setOptions(nfcPosition = ...), alebo ho prepíšte pre jednotlivé volanie cez pay(..., nfcPosition = ...). setOptions() mení len tie voľby, ktoré odovzdáte, takže samotné setOptions(nfcPosition = ...) nenaruší skôr nastavenú predvolenú hodnotu receiptConfig a naopak.

Nastavenie časového limitu transakcie

transactionTimeout určuje, ako dlho plugin Tapaya Terminal čaká, kým zákazník priloží kartu, než to vzdá. Prijíma akúkoľvek hodnotu Duration od nuly do 120 sekúnd; čokoľvek mimo tohto rozsahu sa prejaví ako TransactionTimeoutOutOfRange(transactionTimeout) cez PaymentEvent.CreationFailed, pretože pay() nikdy nevyhadzuje výnimku synchrónne.

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

Ponechajte predvolenú hodnotu null, ak chcete použiť vlastný záložný limit sprievodnej aplikácie (približne 60 sekúnd), alebo nastavte predvolenú hodnotu pre celé zariadenie pomocou Accept.payments.setOptions(transactionTimeout = ...).

Voľba displeja

Pri obojstrannom zariadení („double-sided“) je jeden panel otočený k obchodníkovi a druhý, zákaznícky panel k platiteľovi. Accept.displays hlási, aké displeje má zariadenie práve teraz, a voľba display hovorí pluginu, na ktorom paneli má spustiť svoje platobné UI.

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

Cieľ, ktorý nemožno splniť, napríklad CustomerFacing na zariadení s jednou obrazovkou, potichu prejde na Default. Predvolené nastavenie pre celé zariadenie nastavte pomocou Accept.payments.setOptions(display = ...), alebo ho prepíšte pre jednotlivé volanie cez pay(..., display = ...).

Ukážková aplikácia :dualscreen predvádza kompletné platenie na dvoch paneloch: obchodník pracuje na primárnom paneli, zatiaľ čo PaymentDisplay.CustomerFacing zobrazí platobné UI pluginu na obrazovke zákazníka.

Výsledok platby

Konečná udalosť PaymentEvent.Result nesie PayResult. Každý variant nesie metadata, ktoré vracajú to, čo ste odovzdali do pay(), ak ich plugin vráti (môže byť null):

PayFailureReason je jedna z hodnôt INVALID_INTENT, NOT_ACTIVATED, TERMINAL_INIT_FAILED, PAYMENT_SETUP_FAILED, PLUGIN_UNAVAILABLE alebo UNKNOWN.

Čítanie údajov účtenky

Success a Declined nesú voliteľné receiptDetails: ReceiptDetails? so štruktúrovanými údajmi kartovej účtenky hlásenými terminálom, určené pre volajúcich, ktorí tlačia vlastnú oficiálnu kartovú účtenku namiesto toho, aby sa spoliehali len na hostovanú stránku PaymentStatus.receiptUrl.

Každé pole je voliteľné a bez záruky; volajúci musí počítať s tým, že ktorékoľvek z nich, prípadne aj samotné receiptDetails, bude chýbať.

Čítanie podrobností platby

PayResult.Success vám poskytne paymentToken. Úplný záznam vrátane receiptUrl, požadovanej a zúčtovanej sumy a časových pečiatok načítate pomocou Accept.payments.status():

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

Prebiehajúcu platbu zastavíte pomocou Accept.payments.cancel(paymentToken), ktoré vracia výsledný PaymentState.

Vrátenie platby

Dokončenú platbu vrátite pomocou Accept.payments.refund(paymentToken, reason), ktoré tiež vracia výsledný PaymentState.

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

RefundReason je jedna z hodnôt CUSTOMER_REQUEST, DUPLICATE, FRAUDULENT alebo EXPIRED_CHARGE.

Spracovanie chýb

Platba, ktorá sa dostane do terminálu, ale neuspeje, nie je výnimka; príde ako PaymentEvent.Result s PayResult.Declined, Canceled alebo Failed(reason). Zlyhania, ktoré zabránia vytvoreniu platby, prichádzajú ako PaymentEvent.CreationFailed(cause), kde cause je typovaná AcceptException. Výnimky špecifické pre túto integráciu:

Accept.payments.status(), cancel() a refund() sú funkcie suspend a tieto výnimky vyhadzujú (namiesto vysielania udalostí); obaľte ich do try-catch. status()/cancel()/refund() navyše pri neznámom tokene vyhadzujú PaymentNotFound. Úplný zoznam nájdete v časti Spracovanie chýb.

Časové limity

Platba kartou sa musí na termináli dokončiť krátko po jej spustení. Ak zákazník kartu nikdy nepriloží alebo sa plugin Tapaya Terminal počas platby zatvorí, platba skončí ako PayResult.Canceled alebo PayResult.Failed a podkladová platba sa na strane servera zruší a nikdy sa nezúčtuje. Predtým, ako platbu budete považovať za dokončenú, vždy si overte konečný stav pomocou Accept.payments.status().

Integrácia bez SDK

Ak nemôžete Accept SDK vložiť do aplikácie (multiplatformový framework, tenký POS shell, webová pokladnica), môžete Tapaya Terminal ovládať priamo pomocou deeplinku. Rozdelenie práce sa tým mení: platbu cez Tapaya API vytvárate vy a vy sa tiež dopytujete na jej stav, aby ste zistili výsledok; Tapaya Terminal zabezpečuje len prácu s kartou.

Postup:

1. Vytvorte platbu zo svojho backendu cez Payments API a uložte si jej paymentId.
2. Otvorte Tapaya Terminal s týmto paymentId pomocou platobného deeplinku.
3. Dopytujte sa na stav platby cez Payments API, kým neopustí stav PENDING. Deeplinky nemajú spätný kanál, takže dopytovanie je jediným spoľahlivým zdrojom výsledku.

Schémy deeplinkov

Schéma určuje, ktoré zostavenie Tapaya Terminal odkaz obslúži:

Ak sa odkaz nepodarí otvoriť, dané zostavenie Tapaya Terminal nie je nainštalované.

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

Prihlasovací deeplink

Prihláste obchodníka do Tapaya Terminal pomocou jeho merchantToken, identifikátora obchodníka, ktorý nastavíte cez POST /merchant/auth/register:

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

Otestovanie integrácie

1. Inicializujte s isProduction = false (predvolená hodnota); platby v sandboxe nikdy nepresúvajú skutočné peniaze.
2. Nainštalujte plugin Tapaya Terminal do testovacieho zariadenia, prihláste sa testovacím obchodníkom zo sandboxu a vykonajte aktiváciu.
3. Vykonajte platbu na malú sumu a overte celý tok Success od začiatku do konca vrátane vášho UI účtenky.
4. Vyskúšajte cesty zlyhania: zamietnite platbu na termináli, jednu zrušte a jednu spustite v nepodporovanej mene; vaše spracovanie PayResult/CreationFailed by malo pokryť každú z nich.

Keď budete pripravení spustiť ostrú prevádzku, nastavte v initialize hodnotu isProduction = true a autentifikujte sa s produkčnými prihlasovacími údajmi. Kód platieb sa nemení.