Краткая последовательность:
- Создание платежа (order) на вашем бэкенде.
- Отправка запроса в провайдер: «создание платежа через API» с суммой, валютой, описанием и параметрами возвратов/подписок.
- Провайдер возвращает состояние: требуется 3‑D Secure подтверждение, редирект, или мгновенное подтверждение.
- Клиент проходит аутентификацию (3‑D Secure/SDK/редирект).
- Провайдер завершает авторизацию/списание и отправляет webhook.
- Ваш бэкенд фиксирует статус, обновляет заказ и показывает результат пользователю.
Выбор провайдера и модели интеграции
Выбор провайдера влияет на комиссии, конверсию, поддержку методов оплаты и сложность внедрения. Начните с оценки модели интеграции и требований PCI DSS.
Варианты интеграции:
| Модель |
Что это |
Когда выбирать |
3‑D Secure |
Нагрузка по PCI |
| Redirect/Hosted Page |
Клиент временно уходит на платежную страницу провайдера |
Быстрый старт, минимум комплаенса |
Обрабатывается провайдером |
Низкая |
| Hosted Fields |
Поля карты в iframe провайдера, UI контролируете вы |
Компромисс UX и безопасности |
Обрабатывается провайдером |
Средняя |
| Full API (own form) |
Вы собираете данные карты и шифруете |
Максимальный контроль и кастом |
Отправляете на 3‑D Secure сами |
Высокая (PCI DSS SAQ D) |
Полезные материалы:
- Кому подойдет банк, а кому агрегатор — смотрите обзор: Банки vs агрегаторы.
- Профили провайдеров и особенности API:
Требования к безопасности и 3‑D Secure подтверждение
При работе с картами учитывайте PCI DSS и SCA/3‑D Secure. 3‑D Secure подтверждение снижает мошенничество и переносит ответственность на эмитента при соблюдении правил. В зависимости от провайдера вы получите URL для редиректа, challenge‑поток либо параметры для SDK.
- Минимизируйте хранение чувствительных данных — используйте токены.
- Обновляйте сертификаты/ключи и шифруйте трафик (TLS 1.2+).
- Пройдите чек‑лист по безопасности и 3DS: PCI DSS и 3‑D Secure.
Подготовка окружения и тестирование
Перед продакшеном разверните окружения DEV/STAGE и подключите песочницу провайдера.
- Тестовые карты, статусы и сценарии: Песочница и тестовые карты.
- Мобильные приложения: используйте готовые SDK для iOS/Android — это упрощает 3DS и UX: Интеграция мобильных SDK.
- Логи и трейсинг: храните запросы/ответы и заголовки идемпотентности для разборов.
Пошаговая интеграция: создание, подтверждение, webhooks
Ниже — базовый сценарий для карт. Реальные поля и эндпойнты смотрите в документации выбранного провайдера.
Шаг 1. Создание платежа через API
В запросе указывайте сумму, валюту, описание заказа, callback/webhook URL, а также уникальный ключ идемпотентности.
curl -X POST https://api.provider.example/payments \
-H "Authorization: Bearer <YOUR_TOKEN>" \
-H "Idempotency-Key: 9f8d2e4c-1a2b-4bcd-9e01-1234567890ab" \
-H "Content-Type: application/json" \
-d '{
"amount": {"value": "1990.00", "currency": "RUB"},
"capture": true,
"description": "Order #4312",
"confirmation": {"type": "redirect", "return_url": "https://shop.example/thanks"},
"metadata": {"order_id": "4312"},
"receipt": {"customer": {"email": "[email protected]"}},
"webhook_url": "https://shop.example/webhooks/payments"
}'
Ответ может содержать:
- статус pending/awaiting_confirmation;
- URL для редиректа/SDK‑параметры для 3‑D Secure подтверждения;
- мгновенный статус succeeded (иногда для кошельков/быстрых платежей).
Шаг 2. Проведение 3‑D Secure/авторизации
- Если вернулся confirmation_url, редиректните пользователя.
- Для мобильных — откройте SDK‑вью или SFSafariViewController/Custom Tabs.
- По завершении провайдер вернет пользователя на return_url.
Шаг 3. Обработка webhooks платежи
После авторизации провайдер отправит webhook о финальном статусе (succeeded/canceled). В обработчике:
- Проверьте подпись/секрет.
- Сверьте сумму, валюту и order_id.
- Идемпотентно обновите заказ и отразите статус пользователю.
Шаг 4. Повторные запросы и идемпотентность
Сохраняйте Idempotency-Key и payment_id, чтобы безопасно ретраить запросы при сетевых сбоях. Подробнее — в разделе ниже и в гайде: Вебхуки и идемпотентность.
Шаг 5. Частичная/полная отмена и возврат
На этапе пост‑платежных операций используйте API для отмены авторизации (reversal) или возврата (refund). См. детали: Возвраты и реверсалы.
Идемпотентность API и защита от дублей
Идемпотентность API гарантирует, что повторная отправка одного и того же запроса не создаст дубликатов платежей. Практика:
- Генерируйте уникальный Idempotency-Key на уровне заказа/операции (UUID v4).
- Храните соответствие idempotency_key → payment_id в БД.
- Ретрайте безопасно только операции, поддерживающие идемпотентность (создание платежей, возвраты, подтверждения).
- Обрабатывайте 409/422 и ретри с экспоненциальной паузой.
Разработайте единый паттерн для вебхуков и повторов запросов: Вебхуки и идемпотентность.
Возвраты и отмены
Возврат платежа API позволяет вернуть средства полностью или частично. Отличайте:
- Reversal (отмена авторизации) — до списания средств, быстрый возврат «в ноль».
- Refund (возврат) — после списания, может быть частичным, участвует в сверке.
Рекомендации:
- Делайте refund идемпотентным по уникальному ключу операции возврата.
- Храните связь refund → исходный payment_id и документ‑основание.
- Сообщайте клиенту ожидаемый срок финального зачисления (обычно 1–10 дней у банков).
Подробности и примеры статусов: Возвраты и реверсалы.
Повторяющиеся платежи и токенизация
Для подписок и регулярных списаний используйте сохраненные токены (card‑on‑file). Базовый поток:
- Первый платеж с 3‑D Secure подтверждением и сохранением токена.
- Дальнейшие «merchant initiated» операции с использованием токена без участия плательщика (при наличии мандата/оферты).
Важные моменты:
- Указывайте инициатора операции (CIT/MIT) в соответствии с правилами схем.
- Срок жизни токенов и их ротация зависят от провайдера.
- Для пауз/возобновлений поддерживайте статусы подписки на своей стороне.
Шаблоны и советы по подпискам: Повторяющиеся списания и подписки.
Сверка платежей и мониторинг
Даже идеальная интеграция платежей API без качественной сверки будет уязвима к расхождениям. Настройте ежедневную сверку реестров провайдера с вашей БД.
- Автоматизируйте отчеты и акты: Сверка и аналитика.
- Логи и алерты по SLA, утилизации ретраев, времени 3DS‑челленджа.
- Мониторинг ошибок и таймаутов — заведите дашборды и инцидент‑менеджмент: Ошибки и мониторинг.
Чек‑лист перед выходом в прод
- Пройден тест‑план в песочнице (оплата, отмена, частичный и полный возврат, сбои сети): Песочница.
- Включено и протестировано 3‑D Secure подтверждение: PCI DSS и 3‑D Secure.
- Реализована идемпотентность API и безопасные ретраи: Вебхуки и идемпотентность.
- Обработчик webhooks устойчив к повторным доставкам и сбоям.
- Сверка и реестры автоматизированы: Сверка и аналитика.
- Настроены уведомления о деградации конверсии и росте отказов.
- Мобильные сценарии покрыты SDK (если есть приложение): Мобильные SDK.
- Выбран провайдер и модель интеграции, учтены комиссии и поддерживаемые методы: Банки vs агрегаторы и страницы провайдеров.
Заключение и следующий шаг
Интеграция платежей API дает вам контроль над UX, автоматизацию финансовых процессов и гибкость масштабирования. Начните с тестов в песочнице, сформируйте схему платежного потока под ваш продукт, подключите 3‑D Secure подтверждение и выстройте надежную работу webhooks и идемпотентности.
Готовы внедрять? Выберите провайдера (YooMoney, Сбербанк, T‑Bank, Belarusbank), проверьте требования безопасности PCI DSS и 3‑D Secure и запустите первые транзакции в песочнице. Если потребуется расширенная логика (подписки, возвраты, сверка), используйте наши шаблоны: вебхуки и идемпотентность, возвраты и реверсалы, подписки, сверка и аналитика.