Застосунок Tapaya Terminal

Приймайте безконтактні платежі карткою у своєму застосунку для Android, передаючи взаємодію з карткою застосунку-плагіну Tapaya Terminal. Продаж залишається під контролем вашого застосунку; плагін бере на себе прикладання картки через NFC, введення PIN і обробку картки, а потім результат повертається через потік подій Accept.payments.pay().

Використовуйте цю інтеграцію, якщо вам потрібен Tap to Pay без вбудовування платіжного процесора у ваш власний застосунок. Якщо для вашої платформи натомість увімкнено вбудований Tap to Pay, див. посібник Embedded Tap to Pay.

Варіанти інтеграції

Спершу описано шлях через SDK; контракт deeplink див. у розділі Інтеграція без SDK.

Як це працює

1. Ваш застосунок починає платіж викликом Accept.payments.pay(amount, currency).
2. SDK реєструє платіж у бекенді Tapaya і запускає плагін Tapaya Terminal на тому самому пристрої.
3. Клієнт прикладає свою картку або телефон до екрана Tapaya Terminal.
4. Tapaya Terminal завершує обробку платежу з бекендом Tapaya.
5. SDK відстежує платіж, доки той не досягне кінцевого стану, і надсилає PaymentEvent.Result із PayResult. Якщо платіж узагалі неможливо створити, натомість надсилається PaymentEvent.CreationFailed, зазвичай протягом секунди.

Передумови

• Плагін Tapaya Terminal, установлений на пристрої та активований для вашого мерчанта (див. Установлення й активація термінала).
• Пристрій із NFC під керуванням Android 11 (API 30) або новішої версії.
• Accept SDK установлено й ініціалізовано, а мерчант увійшов у систему.
• Дозвіл на доступ до геолокації (ACCESS_FINE_LOCATION), наданий вашому застосунку під час виконання.

Установлення й активація термінала

Активацію виконують один раз для кожного пристрою. Активація пов'язує плагін Tapaya Terminal із тим самим обліковим записом мерчанта, під яким автентифіковано ваш застосунок.

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 набуває одного зі значень INVALID_INTENT, HANDOVER_FAILED, CONFIRM_FAILED, MERCHANT_NOT_ONBOARDED або UNKNOWN.

activateTerminal() також викидає NoTidsAvailableForMerchant, коли в мерчанта не залишилося жодного непризначеного термінала (TID) для активації, окремо від наведених вище результатів ActivateTerminalResult.Failed. Обгорніть виклик у try-catch, якщо хочете окремо показувати цей випадок, наприклад запропонувати мерчанту звільнити або запросити ще один TID.

Перевірка оновлень плагіна

Accept.plugin.updateInfo() повідомляє, чи доступна в Google Play новіша збірка плагіна Tapaya Terminal, щоб ви могли запропонувати мерчанту оновитися до того, як платіж наштовхнеться на розбіжність версій.

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

Створення платежу

Суми завжди вказуються в найменшій одиниці валюти: гелерах для CZK, центах для EUR. 1500 з валютою "CZK" стягує 15,00 Kč. Валюти вказуються кодами ISO 4217.

pay() повертає Flow<PaymentEvent>; збирайте його, щоб стежити за перебігом і кінцевим результатом. Він ніколи не викидає винятків; збої надходять як 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
        }
    }

Параметри:

Поки платіж триває, плагін Tapaya Terminal перебуває на передньому плані. Коли платіж завершується, ваш застосунок автоматично відновлює роботу. Щоб відновити перерваний платіж, передайте його paymentToken назад у pay(amount, currency, paymentToken).

Вибір валюти

pay() стягує оплату у валюті currency, яку ви передаєте як код ISO 4217 великими літерами, а amount вказується в найменшій одиниці цієї валюти. На сторінці Підтримувані валюти наведено всі валюти, які підтримує Tapaya, але мерчанту зазвичай увімкнено лише деякі з них.

Викличте Accept.merchant.availableCurrencies(), щоб отримати коди ISO 4217, увімкнені для мерчанта. Платіж у будь-якій іншій валюті завершується помилкою CurrencyNotAvailableForMerchant.

Кожна валюта також має мінімальну суму платежу, яка діє на рівні всієї платформи. Поточні мінімуми можна отримати за допомогою Accept.sdk.minimumAmounts(), який повертає List<MinimumAmount> (currency: String, amount: Long, у найменшій одиниці валюти). Виклик pay() із сумою, нижчою за цей мінімум, завершується помилкою PaymentEvent.CreationFailed(AmountBelowMinimum(minimum, currency)). Повний перелік винятків див. у розділі Обробка помилок.

Налаштування екрана чека

receiptConfig визначає, що плагін Tapaya Terminal показує платнику після схваленого платежу, як довго це залишається на екрані та чи друкується чек. Він не впливає на відхилені й сторновані платежі чи платежі, що очікують на сторнування; для них завжди показується власний екран результату незалежно від цього налаштування.

Задайте типове налаштування для всього пристрою один раз за допомогою Accept.payments.setOptions() і перевизначайте його для окремого платежу через pay(..., receiptConfig = ...). Доки setOptions() не викликано, типовим значенням є Show із QR-чеком, ручним закриттям і друком на вимогу, що відповідає власному резервному налаштуванню плагіна.

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

nfcPosition є підказкою, яка повідомляє плагіну Tapaya Terminal, де розташована NFC-антена цього пристрою, щоб він міг правильно розмістити анімацію «прикладіть тут». Плагін спершу сам визначає розташування антени (виявленням на платформі в реальному часі, потім за вбудованою базою даних пристроїв, а потім за будь-якими налаштуваннями, які мерчант задав безпосередньо в плагіні); вказуйте це значення лише тоді, коли потрібно перевизначити результат цього визначення, наприклад на пристрої, який плагін не може розпізнати або для якого в його базі даних указано неправильні дані.

Задайте типове налаштування для всього пристрою за допомогою Accept.payments.setOptions(nfcPosition = ...) або перевизначте його для окремого виклику через pay(..., nfcPosition = ...). setOptions() змінює лише передані вами параметри, тож окремий виклик setOptions(nfcPosition = ...) не порушить раніше задане типове значення receiptConfig, і навпаки.

Налаштування тайм-ауту транзакції

transactionTimeout визначає, скільки часу плагін Tapaya Terminal чекає, поки клієнт прикладе картку, перш ніж припинити спробу. Він приймає будь-яке значення Duration від нуля до 120 секунд; будь-яке значення поза цим діапазоном надходить як TransactionTimeoutOutOfRange(transactionTimeout) через PaymentEvent.CreationFailed, оскільки pay() ніколи не викидає винятків синхронно.

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

Залиште типове значення null, щоб використовувати власний резервний тайм-аут супутнього застосунку (близько 60 секунд), або задайте типове значення для всього пристрою за допомогою Accept.payments.setOptions(transactionTimeout = ...).

Вибір дисплея

На двосторонньому («double-sided») пристрої одна панель повернута до мерчанта, а друга, клієнтська панель, повернута до платника. Accept.displays повідомляє, які дисплеї пристрій має зараз, а параметр display вказує плагіну, на якій панелі запускати свій платіжний 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,
)

Ціль, яку неможливо застосувати, наприклад CustomerFacing на пристрої з одним екраном, непомітно замінюється на Default. Задайте типове налаштування для всього пристрою за допомогою Accept.payments.setOptions(display = ...) або перевизначте його для окремого виклику через pay(..., display = ...).

Демонстраційний застосунок :dualscreen показує повний процес оплати на двох панелях: мерчант працює на основній панелі, а PaymentDisplay.CustomerFacing виводить платіжний UI плагіна на екран клієнта.

Результат платежу

Кінцева подія PaymentEvent.Result містить PayResult. Кожен варіант містить metadata, повертаючи те, що ви передали в pay(), якщо плагін їх повертає (може бути null):

PayFailureReason набуває одного зі значень INVALID_INTENT, NOT_ACTIVATED, TERMINAL_INIT_FAILED, PAYMENT_SETUP_FAILED, PLUGIN_UNAVAILABLE або UNKNOWN.

Отримання даних чека

Success і Declined містять необов'язкове поле receiptDetails: ReceiptDetails? зі структурованими даними карткового чека, які повідомляє термінал. Воно призначене для тих, хто друкує власний офіційний картковий чек, а не покладається лише на розміщену сторінку PaymentStatus.receiptUrl.

Кожне поле є необов'язковим і заповнюється без гарантій; код, що викликає, має бути готовим до того, що будь-яке з них або саме receiptDetails буде відсутнім.

Отримання даних платежу

PayResult.Success надає вам paymentToken. Повний запис, зокрема receiptUrl, запитану суму й суму розрахунку, а також позначки часу, можна отримати за допомогою 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

Зупинити платіж, що триває, можна за допомогою Accept.payments.cancel(paymentToken), який повертає підсумковий PaymentState.

Повернення коштів

Повернути кошти за завершеним платежем можна за допомогою Accept.payments.refund(paymentToken, reason), який також повертає підсумковий PaymentState.

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

RefundReason набуває одного зі значень CUSTOMER_REQUEST, DUPLICATE, FRAUDULENT або EXPIRED_CHARGE.

Обробка помилок

Платіж, який дійшов до термінала, але не був успішним, не є винятком; він надходить як PaymentEvent.Result із PayResult.Declined, Canceled або Failed(reason). Збої, що не дають створити платіж, надходять як PaymentEvent.CreationFailed(cause), де cause є типізованим AcceptException. Винятки, специфічні для цієї інтеграції:

Accept.payments.status(), cancel() і refund() є функціями suspend і викидають ці винятки (а не надсилають події); обгортайте їх у try-catch. status()/cancel()/refund() також викидають PaymentNotFound для невідомого токена. Повний перелік див. у розділі Обробка помилок.

Тайм-аути

Платіж карткою потрібно завершити на терміналі невдовзі після його початку. Якщо клієнт так і не прикладе картку або плагін Tapaya Terminal закриється посеред платежу, платіж завершиться як PayResult.Canceled або PayResult.Failed, а відповідний платіж буде скасовано на стороні сервера, і він ніколи не буде проведений. Завжди перевіряйте кінцевий стан за допомогою Accept.payments.status(), перш ніж вважати платіж завершеним.

Інтеграція без SDK

Якщо ви не можете вбудувати Accept SDK (кросплатформний фреймворк, тонка POS-оболонка, вебкаса), ви можете керувати Tapaya Terminal напряму за допомогою deeplink. Розподіл роботи змінюється: ви створюєте платіж через Tapaya API і ви опитуєте його статус, щоб отримати результат; Tapaya Terminal відповідає лише за взаємодію з карткою.

Послідовність:

1. Створіть платіж зі свого бекенда через Payments API і збережіть його paymentId.
2. Відкрийте Tapaya Terminal із цим paymentId за допомогою платіжного deeplink.
3. Опитуйте статус платежу через Payments API, доки він не вийде зі стану PENDING. Deeplink не має зворотного каналу, тому опитування є єдиним надійним джерелом результату.

Схеми deeplink

Схема визначає, яка збірка Tapaya Terminal обробляє посилання:

Якщо посилання не відкривається, цю збірку Tapaya Terminal не встановлено.

Платіжний 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
}

Deeplink для входу

Виконайте вхід мерчанта в Tapaya Terminal за допомогою його merchantToken, ідентифікатора мерчанта, який ви задаєте через POST /merchant/auth/register:

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

Тестування інтеграції

1. Ініціалізуйте з isProduction = false (значення за замовчуванням); платежі в пісочниці ніколи не переказують реальні гроші.
2. Установіть плагін Tapaya Terminal на тестовий пристрій, увійдіть як мерчант пісочниці та виконайте активацію.
3. Проведіть платіж на невелику суму й перевірте весь сценарій Success від початку до кінця, зокрема ваш UI чека.
4. Перевірте сценарії збоїв: відхиліть платіж на терміналі, скасуйте інший і почніть ще один у непідтримуваній валюті; ваша обробка PayResult/CreationFailed має охоплювати кожен із них.

Коли будете готові перейти в робочий режим, задайте isProduction = true в initialize і автентифікуйтеся з обліковими даними робочого середовища. Код платежів не змінюється.