CloudPayments
Войти

API‑интеграция: сервер‑сервер, подписи, webhooks и идемпотентность

Получить CloudPayments бесплатно

API‑интеграция: сервер‑сервер, подписи, webhooks и идемпотентность

Зачем бизнесу S2S‑подход

API интеграция оплаты на модели сервер‑сервер (Server‑to‑Server, S2S) дает полный контроль над платежными потоками: вы формируете платежи на бэкенде, подписываете запросы, принимаете webhooks и самостоятельно управляете UX. Это подходит, когда нужна кастомная логика, сложные статусы, собственная антифрод‑сигнализация, а также при работе с маркетплейсами и выплатами.

Если вы только выбираете провайдера, начните со сравнения условий и возможностей: Выбор платежного провайдера. А если нужна быстрая интеграция без кода, посмотрите готовые коннекторы для CMS в разделе ниже.

![Схема потоков S2S оплаты — placeholder]

Сервер‑сервер модель: базовый поток

Базовый S2S‑поток оплаты состоит из нескольких шагов:

Получить CloudPayments бесплатно
  1. Ваш сервер создает у провайдера сущность «платеж» (или «интенция») через API.
  2. Клиент проходит аутентификацию в банке (3‑D Secure/Challenge), редиректится на провайдера и обратно или остаётся в вашей веб‑вью.
  3. Провайдер отправляет webhook с результатом (async статус платежа).
  4. Вы подтверждаете/фиксируете заказ и отдаёте пользователю итоговый экран.

Синхронный ответ API обычно не финальный — итог фиксируется webhook’ом. Поэтому важны идемпотентность платежей, корректная обработка повторной доставки и порядок событий.

Синхронно vs асинхронно

Характеристика Синхронный ответ API Webhook (асинхронно)
Когда приходит Сразу после запроса Через секунды/минуты
Что означает Предварительный статус (created/pending) Финальный статус (succeeded/failed/refunded)
Надёжность Может потеряться при сетевой ошибке Поддерживает ретраи от провайдера
Рекомендация Не полагаться как на «истину» Хранить как источник истины

Подробнее о вариациях UX и конверсии — в материале Checkout UX и конверсия.

Сущности: платеж и заказ

Разделяйте бизнес‑сущность «заказ» и платежную «платеж». Это упрощает повторные попытки, частичные возвраты и мультисплит.

Сущность Назначение Ключевые поля Примечания
Заказ Что покупает клиент order_id, позиции, суммы, налоги Может жить без платежа
Платеж Как оплачивает клиент payment_id, метод, статус Может быть несколько на один заказ

В API держите связь через order_id и внешние идентификаторы мерчанта (merchant_order_id). Это облегчает аудит и восстановление после сбоев.

Подпись запросов и подпись webhooks

Критично проверять подлинность всех сообщений: и исходящих к провайдеру, и входящих webhooks. Чаще используются HMAC‑SHA256 или RSA.

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

  • Храните секреты для подписи в хранилищах секретов (KMS, Vault), с ротацией ключей.
  • Подписывайте не только тело, но и канонизированный набор заголовков и таймстамп, чтобы защититься от повторов.
  • Для каждой версии ключа храните key_id (kid), чтобы принимать ротацию без даунтайма.

Пример проверки HMAC подписи webhook (псевдокод):

function verifyWebhook(signatureHeader, timestampHeader, body, secret) {
  if (abs(now() - timestampHeader) > 300) return false; // 5 минут
  const base = timestampHeader + "." + canonicalize(body)
  const expected = HMAC_SHA256(base, secret)
  return timingSafeEqual(expected, signatureHeader)
}

Больше про общую безопасность: PCI DSS, 3DS и антифрод.

Идемпотентность платежей и ключи

Идемпотентность платежей защищает от двойного списания из‑за повторной отправки запроса (повтор клика, сетевой таймаут, ретраи). Используйте заголовок Idempotency‑Key или уникальный request_id на уровне create/payment.

Правила:

  • Генерируйте уникальный ключ на каждое намерение оплаты (UUIDv4), привязывайте к order_id.
  • Кэшируйте результат в провайдере и у себя, чтобы повторный запрос возвращал тот же payment_id и статус.
  • Для небезопасных повторов (например, при изменении суммы) возвращайте конфликт.

Мини‑пример запроса:

POST /payments
Headers: Idempotency-Key: 3f01c2d0-...
Body: {"order_id":"12345","amount":1000,"currency":"RUB"}

Webhooks: доставка, порядок, безопасность

Принимайте webhooks как «источник истины» по статусу. Ключевые моменты:

  • Доставка минимум «по крайней мере один раз». Готовьте идемпотентные хэндлеры.
  • Порядок не гарантирован. Сравнивайте версионность (event_id/sequence) или храните дерево статусов.
  • Подпись webhooks обязательна. См. раздел про «подпись webhooks» выше.
  • Возвращайте 2xx только после успешной фиксации статуса в вашей БД.
  • Если вы не можете обработать, верните 5xx — провайдер повторит.

Рекомендуемая структура события:

  • event_type (payment.succeeded, payment.failed, refund.succeeded)
  • payment_id, order_id
  • amount, currency, method
  • status_changed_at (UTC)
  • signature, kid

Очереди сообщений, ретраи и таймауты

Надёжность обеспечивается архитектурой:

  • Очереди сообщений (RabbitMQ/Kafka/SQS) между веб‑воркерами и бизнес‑логикой. Это защищает от всплесков webhooks.
  • Ретраи и таймауты: используйте экспоненциальный backoff, дед‑леттер очередь для событий, которые не удаётся обработать.
  • Таймауты HTTP: клиент → провайдер 10–30с; провайдер → ваш приемник webhooks 5–10с.
  • Лимит попыток: например, 5 быстрых, затем 10 отложенных (1м, 5м, 15м…).

С помощью очередей вы отделяете приём webhooks (легковесный эндпоинт) от «тяжёлой» доменной логики (актуализация заказов, фискализация, e‑mail).

Хранение токенов и безопасность

Если вы храните токены карт или платежные токены для подписок, соблюдайте минимум:

  • Никогда не храните PAN/CVV. Работайте с токенами провайдера.
  • Ограничьте доступ к токенам по принципу наименьших прав. Шифруйте в at‑rest и в транзите.
  • Делайте регулярную ротацию ключей и аудит доступа.

Для подписок и рекуррентных сценариев см. раздел Рекуррентные платежи и подписки. Если планируете мобильную оплату, посмотрите Мобильные SDK iOS/Android и Банковские карты, Apple Pay/Google Pay.

Фискализация, возвраты и статусы

В России онлайн‑касса обязательна. При S2S интеграции вы либо делегируете фискализацию провайдеру, либо отправляете данные в ОФД самостоятельно. Подробнее: Онлайн‑касса, 54‑ФЗ и фискализация.

Возвраты и чарджбеки:

Async статус платежа должен синхронизироваться с вашими состояниями заказа: paid, canceled, refunded, partial_refunded.

Тестирование и запуск в прод

Работайте через песочницу: создайте автотесты для ключевых потоков, мокируйте сетевые сбои и задержки webhooks. Полный гайд: Тестирование, sandbox, webhooks и запуск.

Чек‑лист перед запуском:

  • Проверка идемпотентности всех write‑методов
  • Ротация и валидация ключей подписи
  • Интеграционные тесты с 3‑D Secure/Challenge
  • Маскировка PII и логирование без платежных данных
  • Нагрузочное тестирование webhooks

Также оцените комиссии и экономику: Тарифы и комиссии: эквайринг. При трансграничной работе — Мультивалюта, налоги, валютконтроль.

Интеграции с CMS/SDK и сценарии

Если нужен быстрый старт, существуют готовые модули:

Для сложной логистики или сплит‑платежей посмотрите Маркетплейсы, SaaS и white‑label. Если вы только начинаете — вот краткое руководство: Как подключить платежную систему.

Мониторинг и чек‑лист best practices интеграции

Метрики и алерты:

  • Доля успешной обработки webhooks (2xx) > 99.9%
  • Задержка доставки «платеж → финальный статус» (p95)
  • Количество ретраев, размер дед‑леттер очереди
  • Несоответствия статусов «у нас» vs «у провайдера»
  • Частота таймаутов и сетевых ошибок

Best practices интеграции:

  • Используйте идемпотентность для всех операций изменения состояния.
  • Делайте подпись webhooks и верификацию на стороне сервера.
  • Храните «сущности платеж заказ» раздельно и связывайте через внешние ключи.
  • Вводите «окно согласования» (grace period) для отложенных статусов.
  • Используйте очереди сообщений и изолируйте критичные участки.
  • Реализуйте экспоненциальный backoff для ретраев и лимитируйте таймауты.
  • Логи структурируйте: request_id, payment_id, order_id, event_id.
  • Документируйте контракты API и версии; вносите изменения через v2/v3.

Короткий пример потока S2S

  • create payment (идемпотентно)
  • получить client_action (redirect/3DS)
  • ожидать async статус платежа через webhook
  • зафиксировать заказ, запустить фискализацию
  • отправить чек/уведомление клиенту
  • при ошибке — инициировать повторную попытку или альтернативный метод (например, СБП)

Вывод и следующий шаг

API интеграция оплаты по модели сервер‑сервер дает гибкость и контроль, но требует дисциплины: подпись запросов и подпись webhooks, идемпотентность платежей, очереди сообщений, ретраи и таймауты, безопасное хранение токенов и проработанный async статус платежа. Следуйте best practices интеграции, подключайте мониторинг и тестируйте сценарии сбоев.

Готовы перейти к проектированию? Свяжитесь с нами, и мы поможем выбрать провайдера, спроектировать S2S‑архитектуру и быстро запустить оплату — от UX до фискализации.

Получить CloudPayments бесплатно