Привязка карты (Card Bind)

Процесс привязки платёжной карты пользователей партнёрского мобильного приложения через Paylov, интеграция backend'а и приём webhook-уведомлений.

Почему именно так

Поскольку у партнёра нет сертификата PCI DSS, номер карты (PAN) никогда не попадает ни в backend, ни во frontend-код партнёра. Номер карты вводится только на защищённой странице (webview) в домене Paylov. Партнёр получает лишь готовый cardId и результат привязки.

Процесс

1. Backend партнёра запрашивает у Paylov одноразовую ссылку для привязки (bindUrl) — Создание ссылки для привязки.
2. Приложение партнёра открывает эту ссылку в webview. Пользователь вводит номер карты и подтверждает SMS-код — карта активируется на стороне Paylov.
3. Paylov отправляет webhook на backend партнёра — с ID карты и её данными — Webhook.
4. (Необязательно) Если webhook не дошёл, backend партнёра проверяет результат сам — Проверка статуса.

Внутренняя логика страницы webview (дизайн, форма, ввод SMS) готовится командой frontend Paylov — от партнёра не требуется никакой дополнительной работы.

Аутентификация

Запросы backend'а (создание ссылки и проверка статуса) используют тот же merchant Bearer-токен, что и существующий Paylov Subscribe API:

Authorization: Bearer < ACCESS_TOKEN >

Webview не требует никакого токена — он работает только через одноразовый token, который получается при создании ссылки и уже встроен в bindUrl.

Открытие webview

Партнёр лишь открывает полученный bindUrl в обычном компоненте webview.

Android (Kotlin) — пример

val webView = WebView(context)
webView.settings.javaScriptEnabled = true
webView.loadUrl(bindUrl) // bindUrl получен из ответа на создание ссылки

iOS (Swift, WKWebView) — пример

let webView = WKWebView(frame: view.bounds)
webView.load(URLRequest(url: URL(string: bindUrl)!))

React Native — пример

import { WebView } from 'react-native-webview';

<WebView source={{ uri: bindUrl }} />

Пользователь вводит номер карты на странице, подтверждает SMS-код. После завершения процесса страница может перейти на returnUrl (если он был указан при создании ссылки) — в этом случае приложению партнёра следует закрыть webview. Однако основным и надёжным источником результата является webhook, а не сам webview.

После привязки

Получив cardId, партнёр использует его через уже существующий Paylov Subscribe API — здесь ничего не меняется:

Endpoint	Назначение
GET /merchant/userCard/getCard/{cardId}/	Получение данных и баланса карты
GET /merchant/userCard/getAllUserCards/	Все карты пользователя
DELETE /merchant/userCard/deleteUserCard/	Удаление карты
POST /merchant/receipts/pay/ и т.д.	Оплата с использованием cardId

Коды ошибок

Код	HTTP	Значение
permission_denied	400	Merchant не подключён к Subscribe API или неверный токен
link_expired	400	Срок действия ссылки истёк (примерно 20 минут)
link_already_used	400	По этой ссылке карта уже привязана

Безопасность — кратко

• Номер карты (PAN) не попадает ни в одну часть системы партнёра (frontend, backend, логи).
• Ссылка в webview одноразовая и временная — повторно использовать её нельзя.
• Webhook защищён Basic Auth — логин/пароль известны только партнёру и Paylov.
• Все запросы должны выполняться только через HTTPS.