API интеграция оплаты на модели сервер‑сервер (Server‑to‑Server, S2S) дает полный контроль над платежными потоками: вы формируете платежи на бэкенде, подписываете запросы, принимаете webhooks и самостоятельно управляете UX. Это подходит, когда нужна кастомная логика, сложные статусы, собственная антифрод‑сигнализация, а также при работе с маркетплейсами и выплатами.
Если вы только выбираете провайдера, начните со сравнения условий и возможностей: Выбор платежного провайдера. А если нужна быстрая интеграция без кода, посмотрите готовые коннекторы для CMS в разделе ниже.
![Схема потоков S2S оплаты — placeholder]
Базовый S2S‑поток оплаты состоит из нескольких шагов:
Синхронный ответ API обычно не финальный — итог фиксируется webhook’ом. Поэтому важны идемпотентность платежей, корректная обработка повторной доставки и порядок событий.
| Характеристика | Синхронный ответ API | Webhook (асинхронно) |
|---|---|---|
| Когда приходит | Сразу после запроса | Через секунды/минуты |
| Что означает | Предварительный статус (created/pending) | Финальный статус (succeeded/failed/refunded) |
| Надёжность | Может потеряться при сетевой ошибке | Поддерживает ретраи от провайдера |
| Рекомендация | Не полагаться как на «истину» | Хранить как источник истины |
Подробнее о вариациях UX и конверсии — в материале Checkout UX и конверсия.
Разделяйте бизнес‑сущность «заказ» и платежную «платеж». Это упрощает повторные попытки, частичные возвраты и мультисплит.
| Сущность | Назначение | Ключевые поля | Примечания |
|---|---|---|---|
| Заказ | Что покупает клиент | order_id, позиции, суммы, налоги | Может жить без платежа |
| Платеж | Как оплачивает клиент | payment_id, метод, статус | Может быть несколько на один заказ |
В API держите связь через order_id и внешние идентификаторы мерчанта (merchant_order_id). Это облегчает аудит и восстановление после сбоев.
Критично проверять подлинность всех сообщений: и исходящих к провайдеру, и входящих webhooks. Чаще используются HMAC‑SHA256 или RSA.
Рекомендации:
Пример проверки 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.
Правила:
Мини‑пример запроса:
POST /payments
Headers: Idempotency-Key: 3f01c2d0-...
Body: {"order_id":"12345","amount":1000,"currency":"RUB"}
Принимайте webhooks как «источник истины» по статусу. Ключевые моменты:
Рекомендуемая структура события:
Надёжность обеспечивается архитектурой:
С помощью очередей вы отделяете приём webhooks (легковесный эндпоинт) от «тяжёлой» доменной логики (актуализация заказов, фискализация, e‑mail).
Если вы храните токены карт или платежные токены для подписок, соблюдайте минимум:
Для подписок и рекуррентных сценариев см. раздел Рекуррентные платежи и подписки. Если планируете мобильную оплату, посмотрите Мобильные SDK iOS/Android и Банковские карты, Apple Pay/Google Pay.
В России онлайн‑касса обязательна. При S2S интеграции вы либо делегируете фискализацию провайдеру, либо отправляете данные в ОФД самостоятельно. Подробнее: Онлайн‑касса, 54‑ФЗ и фискализация.
Возвраты и чарджбеки:
Async статус платежа должен синхронизироваться с вашими состояниями заказа: paid, canceled, refunded, partial_refunded.
Работайте через песочницу: создайте автотесты для ключевых потоков, мокируйте сетевые сбои и задержки webhooks. Полный гайд: Тестирование, sandbox, webhooks и запуск.
Чек‑лист перед запуском:
Также оцените комиссии и экономику: Тарифы и комиссии: эквайринг. При трансграничной работе — Мультивалюта, налоги, валютконтроль.
Если нужен быстрый старт, существуют готовые модули:
Для сложной логистики или сплит‑платежей посмотрите Маркетплейсы, SaaS и white‑label. Если вы только начинаете — вот краткое руководство: Как подключить платежную систему.
Метрики и алерты:
Best practices интеграции:
API интеграция оплаты по модели сервер‑сервер дает гибкость и контроль, но требует дисциплины: подпись запросов и подпись webhooks, идемпотентность платежей, очереди сообщений, ретраи и таймауты, безопасное хранение токенов и проработанный async статус платежа. Следуйте best practices интеграции, подключайте мониторинг и тестируйте сценарии сбоев.
Готовы перейти к проектированию? Свяжитесь с нами, и мы поможем выбрать провайдера, спроектировать S2S‑архитектуру и быстро запустить оплату — от UX до фискализации.