Інтеграція платіжного шлюзу ЮKassa в мобільний додаток

Інтеграція платіжного шлюзу ЮKassa в мобільному додатку

ЮKassa (бувший Яндекс.Касса) — один з найпопулярніших платіжних шлюзів для російського ринку. Мобільний SDK підтримує оплату картою, через SberPay, SBP, Apple Pay, Google Pay та гаманець ЮMoney. Інтеграція будується навколо токенізації платіжних даних на клієнті з подальшим списанням через серверний API.

Архітектура: токенізація замість реквізитів

ЮKassa не передає карточні дані прямо на ваш сервер. Клієнтський SDK створює платіжний токен — зашифрований об'єкт, який працює одноразово і тільки для вашого магазину. Сервер використовує цей токен для створення платежу через ЮKassa API.

iOS: YooKassaPayments SDK

// Podfile
pod 'YooKassaPayments'

// або SPM
.package(url: "https://github.com/yoomoney/yookassa-payments-swift", from: "7.x.x")

Запуск платіжного екрану:

import YooKassaPayments

let inputData = TokenizationModuleInputData(
    clientApplicationKey: "live_your_client_key",  // з особистого кабінету ЮKassa
    title: "Your Company",
    subtitle: "Замовлення №1234",
    amount: Amount(value: 1500, currency: .rub),
    paymentTypes: [.bankCard, .sberbank, .sbp, .applePay, .yooMoney],
    savePaymentMethod: .on,   // або .off, .userSelects
    isLoggingEnabled: false
)

let viewController = TokenizationAssembly.makeModule(
    inputData: inputData,
    moduleOutput: self
)
present(viewController, animated: true)

Обробка результату:

extension PaymentViewController: TokenizationModuleOutput {
    func tokenizationModule(
        _ module: TokenizationModuleInput,
        didTokenize token: Tokens,
        paymentMethodType: PaymentMethodType
    ) {
        dismiss(animated: true)
        // token.paymentToken — відправляємо на сервер
        sendTokenToBackend(token.paymentToken, paymentMethodType: paymentMethodType.rawValue)
    }

    func didFinish(on module: TokenizationModuleInput, with error: YooKassaPaymentsError?) {
        dismiss(animated: true)
        if let error = error {
            print("YooKassa error: \(error)")
        }
    }
}

Android: YooKassa Payments SDK

// build.gradle
implementation("ru.yoomoney.sdk.kassa.payments:yookassa-android-sdk:7.x.x")

private val tokenizeLauncher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
        val token = Checkout.createTokenizationResult(result.data!!)
        sendTokenToBackend(
            token.paymentToken,
            token.paymentMethodType.name
        )
    }
}

fun startPayment() {
    val paymentParameters = PaymentParameters(
        amount = Amount(BigDecimal.valueOf(1500), Currency.getInstance("RUB")),
        title = "Your Company",
        subtitle = "Замовлення №1234",
        clientApplicationKey = "live_your_client_key",
        shopId = "your_shop_id",
        savePaymentMethod = SavePaymentMethod.ON,
        paymentMethodTypes = setOf(
            PaymentMethodType.BANK_CARD,
            PaymentMethodType.SBERBANK,
            PaymentMethodType.SBP,
            PaymentMethodType.GOOGLE_PAY,
            PaymentMethodType.YOO_MONEY
        )
    )

    val intent = Checkout.createTokenizeIntent(this, paymentParameters)
    tokenizeLauncher.launch(intent)
}

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

Токен з клієнта передається на сервер, сервер створює платіж:

POST https://api.yookassa.ru/v3/payments
Authorization: Basic base64(shopId:secretKey)
Content-Type: application/json
Idempotence-Key: unique-uuid

{
    "amount": { "value": "1500.00", "currency": "RUB" },
    "capture": true,
    "payment_method_data": {
        "type": "bank_card"
    },
    "confirmation": {
        "type": "mobile_application",
        "return_url": "yourapp://payment/result"
    },
    "payment_token": "token_from_client",
    "description": "Замовлення №1234"
}

Якщо відповідь містить status: pending і confirmation.type: redirect — 3DS вимагає підтвердження. SDK це обробляє автоматично, але при прямій API-інтеграції потрібно відкривати confirmation_url в SFSafariViewController / Custom Tabs.

Типові грабли

clientApplicationKey проти secretKey. В SDK передається лише clientApplicationKey (починається на live_ або test_). secretKey тільки на сервері. Переплутати — API повертає 401, але повідомлення не завжди очевидне.

SavePaymentMethod і оферта. При SavePaymentMethod.ON ЮKassa вимагає, щоб користувач прийняв оферту на рекурентні платежі. SDK показує чекбокс автоматично, але пропустити в користувацькому UI — транзакцію відклонять.

Обсяг робіт

• Підключення YooKassa SDK (iOS / Android / Flutter)
• Налаштування paymentTypes під завдання проекту
• Серверний endpoint для створення та підтвердження платежу
• Налаштування Webhook для остаточного статусу
• Тестування в тестовому магазині ЮKassa

Терміни

2–3 дні. Вартість розраховується індивідуально.