API и SDK для интернет‑эквайринга: техническое руководство

Table of contents

• Зачем нужны API и SDK эквайринга
• Архитектура и поток данных
• Быстрый старт: инициация платежа через API
• Идемпотентность: Idempotency-Key
• Webhook платежи: события, подпись, ретраи
• Обработка ошибок API и retry policy
• Tokenization cards и рекуррентные списания
• SDK эквайринг: веб, iOS и Android
• Меры безопасности API и соответствие требованиям
• Песочница, мониторинг и аналитика
• Интеграция с CMS и backend‑стеком
• Дополнительные возможности: SBP, split и международные платежи
• Итоги и следующий шаг

Зачем нужны API и SDK эквайринга

API интернет‑эквайринг — это программный интерфейс, позволяющий вашему сайту или приложению принимать оплату банковскими картами, SBP и альтернативными методами в онлайне. SDK эквайринг дополняет API готовыми клиентскими компонентами: формы оплаты, токенизацию, 3‑D Secure, обработку ошибок UI и безопасную работу с карточными данными.

• Если вы только изучаете тему, начните со страницы «Интернет‑эквайринг».
• Для подключения тарифа и договоров см. «Как подключить» и «Тарифы и комиссии».

Архитектура и поток данных

Классический поток оплаты включает создание платежа на сервере, подтверждение на стороне клиента и асинхронные уведомления о статусе через webhook платежи.

![Схема процесса оплаты: Клиент → Сайт/Приложение → Ваш сервер → API платежного провайдера → Банк/3‑DS → Webhook → Ваш сервер]

Ключевые сущности и эндпоинты API интернет эквайринг:

Метод	Путь	Назначение	Авторизация
POST	/payments	Создание платежа (инициация платежа API)	Bearer/HMAC
GET	/payments/{id}	Получение статуса платежа	Bearer/HMAC
POST	/payments/{id}/confirm	Подтверждение (capture)	Bearer/HMAC
POST	/refunds	Возврат средств	Bearer/HMAC
POST	/tokens	Tokenization cards (токенизация карт)	Public key
POST	/webhooks/test	Тестовая отправка webhook	Bearer/HMAC

Советы по проектированию:

• Разделяйте серверную логику (создание платежа, валидация подписей) и клиентскую (сбор данных карты, 3‑D Secure, UX).
• Всегда храните финальный статус по webhook; запросы к API используйте для верификации и восстановления состояния.
• Для соблюдения 54‑ФЗ подключите отправку чеков через кассу: см. «54‑ФЗ: онлайн‑касса».

Быстрый старт: инициация платежа через API

Ниже — минимальный сценарий «создать → подтвердить → получить статус». Это ориентир; фактические поля зависят от провайдера.

Шаг 1. Создайте платеж (инициация платежа api):

• Передайте сумму, валюту, описание, idempotency ключ, данные покупателя.
• Если используете токен, передайте token вместо «сырых» карточных реквизитов.

Шаг 2. Проведите аутентификацию клиента:

• Для карт — 3‑D Secure challenge; для СБП — QR/линк‑согласие (см. «СБП и QR‑платежи»).

Шаг 3. Подтвердите и зафиксируйте результат:

• Используйте capture или auto‑capture в зависимости от модели (двухстадийная или одноэтапная).
• Дождитесь webhook платежи с финальным статусом и обновите заказ.

Полезно: оформите карту полей запроса/ответа и используйте одинаковые имена заказов (order_id) по всей системе, чтобы упростить трассировку.

Идемпотентность: Idempotency-Key

Идемпотентность гарантирует, что повторная отправка одного и того же запроса не создаст дубликатов платежей.

Как реализовать:

• Для каждого создания платежа генерируйте уникальный idempotency ключ (UUID v4) и передавайте его в заголовке Idempotency-Key.
• Храните маппинг «Idempotency-Key → payment_id, статус» не менее 24 часов.
• При сетевых сбоях безопасно повторяйте запрос с тем же ключом и теми же параметрами.

Когда применять ретраи с идемпотентностью:

• POST /payments (создание)
• POST /refunds (возврат)

Не используйте ретраи для операций, которые могут изменить сумму/состав корзины без идемпотентности, чтобы не получить расхождения.

Webhook платежи: события, подпись, ретраи

Webhook — основной источник правды о финальном статусе. Принимайте уведомления на выделенный endpoint, защищенный аутентификацией и верификацией подписи.

Типовые события:

Событие	Описание	Ключевые поля	Доставка
payment.succeeded	Платеж успешен	payment_id, amount, currency, order_id	At-least-once
payment.failed	Ошибка/отказ	reason, code, payment_id	At-least-once
refund.succeeded	Возврат завершен	refund_id, amount, payment_id	At-least-once
dispute.opened	Чарджбек/спор	payment_id, reason, deadline	At-least-once

Рекомендации по безопасности и надежности:

• Подпись: проверяйте HMAC‑подпись тела и метку времени, храните «секрет» и план обновления (key rotation).
• Идемпотентность на вашей стороне: проверяйте event_id и не применяйте повторно уже обработанные события.
• Ретраи: отвечайте 2xx только после успешной записи статуса в БД; при 5xx провайдер повторит отправку.

Про споры и возвраты читайте на странице «Возвраты и чарджбеки».

Обработка ошибок API и retry policy

Корректная обработка ошибок API снижает потери и повышает стабильность. Ниже — ориентир по классам ошибок и стратегии retry policy платежи.

Код	Тип	Что означает	Действия клиента	Retry
400	Неверные данные	Валидация, обязательные поля	Исправить запрос	Нет
401/403	Авторизация	Неверный токен/подпись, доступ запрещен	Обновить ключи/права	Нет
402	Отклонение платежа	Банк отказал, фрод, недостаточно средств	Сообщить пользователю, предложить другой метод	Нет
409	Конфликт	Повтор с тем же Idempotency-Key, конфликт статусов	Идемпотентно получить результат	Да (GET)
422	Логическая ошибка	Несовместимые параметры	Исправить логику	Нет
429	Лимиты	Превышен rate limit	Экспоненциальный backoff + jitter	Да
500/503	Внутренние ошибки	Временная недоступность	Повтор с backoff, та же идемпотентность	Да

Best practices:

• Экспоненциальный backoff (например, 1s, 2s, 4s, 8s) + jitter для избежания «стадного эффекта».
• Четкая «обработка ошибок api»: логируйте correlation_id, idempotency ключ, endpoint, payload без чувствительных данных.
• Для «инициация платежа api» повторяйте только с тем же Idempotency-Key.

Tokenization cards и рекуррентные списания

Tokenization cards (токенизация карт) позволяет сохранять безопасный токен вместо PAN и CVV. Это сокращает трение при повторных оплатах и дает основу для подписок.

• Токен создается через /tokens в браузере/моб. SDK; сырой PAN не проходит через ваш сервер (SAQ A).
• При оплате передавайте token и customer_id; для регулярных платежей используйте модель «card-on-file» и MIT.
• Повторные списания и подписки описаны в «Рекуррентные платежи».

Если вам нужно делить платежи между продавцами, смотрите «Маркетплейсы и сплит‑платежи».

SDK эквайринг: веб, iOS и Android

SDK эквайринг экономит месяцы разработки:

• Web SDK: хостируемые поля, drop‑in виджет, управление фреймами, автоматический 3‑D Secure 2.
• iOS/Android SDK: нативные экраны, SCA, биометрия, сохраненные карты, Apple Pay/Google Pay.
• Безопасность: шифрование, токенизация на устройстве, certificate pinning.

Веб‑интеграции часто реализуют через CMS и плагины. Начните с «Интеграция с CMS» или готовых модулей. Для ручной интеграции — используйте хостинг JS SDK на доверенных доменах и CSP‑политику.

Меры безопасности API и соответствие требованиям

Надежные меры безопасности api критичны для минимизации рисков и соответствия PCI DSS.

Основы:

• TLS 1.2+ обязательно, отключите устаревшие шифросuites.
• OAuth 2.0 или HMAC‑подпись запросов (добавляйте nonce и timestamp).
• Проверка происхождения webhook и IP allowlist.
• Rate limiting и защита от повторов (replay protection).
• Секреты храните в Vault/KMS; ключи обновляйте по расписанию.

Соответствие:

• При использовании хост‑полей/SDK вы обычно остаетесь в зоне SAQ A. Подробнее — «Безопасность и PCI DSS».
• Для фискализации чеков по 54‑ФЗ — «Онлайн‑касса 54‑ФЗ».

Песочница, мониторинг и аналитика

Разделяйте тестовую и боевую среду:

• Sandbox: тест‑карты и сценарии (успех, 3‑D Secure required, недостаточно средств, фрод).
• Наблюдаемость: корреляция запросов по order_id, payment_id, correlation_id.
• Метрики: авторизация, конверсия в оплату, доля 3‑DS, отказ банка, доля ретраев.

Строить отчеты и воронку поможет «Аналитика и отчеты». Сроки поступления средств ищите на странице «Сроки и зачисления».

Интеграция с CMS и backend‑стеком

Поддерживаются популярные CMS и фреймворки: 1C‑Битрикс, WooCommerce, OpenCart, Shopify, Laravel, Django, Spring, .NET.

Рекомендации:

• Используйте готовые плагины из «Интеграция с CMS».
• На бэкенде реализуйте слой платежного сервиса (facade): API‑клиент, валидатор подписи, обработчик webhook, репозиторий статусов.
• Документацию по полям и статусам держите рядом с кодом; термины смотрите в «Глоссарий».

Дополнительные возможности: SBP, split и международные платежи

Расширьте способы оплаты для роста конверсии:

• СБП и QR — мгновенные переводы, низкая комиссия: «SBP и QR‑платежи».
• Split‑платежи для маркетплейсов: «Маркетплейсы и сплит».
• Валидация карт, поддержка 3‑D Secure 2, Apple/Google Pay.
• Эквайринг в разных валютах и странах — «Международные платежи».

Сравнить провайдеров и стеки комиссий можно в разделе «Сравнение провайдеров» и «Тарифы и комиссии».

Итоги и следующий шаг

API интернет эквайринг и SDK эквайринг дают гибкость и скорость внедрения: от «инициация платежа api» и tokenization cards до надежных webhook платежи, идемпотентности и продуманной «обработка ошибок api». Соблюдайте меры безопасности api, внедряйте retry policy платежи и используйте песочницу для быстрых тестов — и вы получите стабильный платежный контур с высокой конверсией.

Готовы к интеграции? Ознакомьтесь с шагами подключения на странице «Как подключить», загляните в «FAQ», а при необходимости обратитесь в «Служба поддержки». Не забудьте проверить фискализацию по 54‑ФЗ и оптимизировать воронку оплаты в «Оптимизация конверсии».