API интернет‑эквайринга: интеграция, webhooks, примеры

API интернет‑эквайринга — это способ подключить платежи на сайт, в мобильное приложение или ERP через програмный интерфейс. Ниже разбираем архитектуру, webhooks, безопасность, типовые запросы и сравниваем возможности популярных банков.

Что такое API интернет‑эквайринга и когда он нужен

API интернет‑эквайринга — это REST/JSON или gRPC интерфейс платежного шлюза, который позволяет принимать платежи банковскими картами, через СБП, Apple/Google Pay, создавать возвраты, управлять подписками, оформлять фискальные чеки и получать уведомления о статусах. Подробнее о базовых понятиях — в материалах: что такое интернет‑эквайринг и как работает интернет‑эквайринг.

Когда уместно выбирать API:

Нужен полный контроль над платежной логикой, кастомный checkout, one‑click, сохранение токенов.
Масштабируемый backend, интеграция с ERP/CRM/1C.
Автоматические возвраты, частичные списания, отложенные платежи (capture/void).
Высокие требования к UX и аналитике.

Если задача проще (быстрый старт без разработки), можно начать с платежных ссылок и позже перейти на API.

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

Поток платежа через API: от заказа до чека

Типовой сценарий:

Клиент создает заказ на сайте. Вы генерируете order_id на своей стороне.
Backend вызывает endpoint «создать платеж» и получает payment_id + ссылку/параметры для оплаты (HPP, виджет или S2S).
Клиент подтверждает оплату (3‑DS/МирAccept/SBP). Платежный шлюз меняет статус.
Ваш сервер принимает webhook со статусом (authorized, confirmed/paid, canceled, failed).
Вы отгружаете товар/услугу и отправляете данные в ККТ. Про фискализацию — в разделе онлайн‑касса и фискализация.
При необходимости делаете capture/void, возвраты или списания по подписке.

Основные методы API и объекты

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

Объект/метод	Назначение	Когда использовать
POST /payments	Создание платежа (amount, currency, description, customer, return_url)	Старт оплаты с сайта/приложения
GET /payments/{id}	Чтение статуса	Сверка статусов, fallback к вебхукам
POST /payments/{id}/capture	Подтверждение авторизации	Отложенная оплата после проверки наличия товара
POST /payments/{id}/cancel	Отмена авторизации	Если товар недоступен
POST /refunds	Возврат (полный/частичный)	Возвраты, частичные возвраты и частичные списания — см. возвраты и списания
POST /customers	Создание клиента	Для токенизации и подписок
POST /tokens	Токенизация карты/кошелька	One‑click, рекуррентные списания
POST /subscriptions	Создание подписки	Регулярные платежи, см. отключение подписок и спорные списания
POST /webhooks/test	Проверка приема уведомлений	Настройка подписок на события
POST /receipts	Отправка данных в ККТ	Фискализация, онлайн‑чеки

Поддержка СБП/QR (создание invoice/QR‑ссылки) часто вынесена в отдельный раздел API. Детали — в материале Эквайринг СБП.

Быстрый план интеграции

Чтобы интернет эквайринг установить на сайт и запустить прием платежей через API, придерживайтесь следующего порядка:

Выберите банк/провайдера и тариф. Сравните условия: тарифы и комиссии, сравнение тарифов банков, рейтинг провайдеров.
Пройдите подключение интернет‑эквайринга: анкета, KYC, договор, доступы к sandbox.
Получите ключи (public/secret), настройте IP‑списки, подписи (HMAC/JWT), OAuth2 (если требуется). Подробнее — правила и требования.
Реализуйте создание платежа и прием webhooks. Сохраняйте idempotency‑key на каждый бизнес‑заказ.
Подключите фискализацию и протестируйте связку ККТ: онлайн‑касса и фискализация, связка ККТ/АТОЛ/Эвотор.
Покройте тестами happy‑path и негативные сценарии: тестовый стенд и песочница, инструкция и примеры.
Настройте мониторинг: повторная доставка webhooks, алерты по доле отказов, таймаутам, 3‑DS.

Webhooks: статусы, подписи и ретраи

Уведомления от эквайера — ключ к надежной пост‑обработке.

Какие события: payment.created, payment.authorized, payment.confirmed (paid), payment.canceled, payment.failed, refund.succeeded/failed, subscription.renewed.
Безопасность: верифицируйте подпись (HMAC-SHA256 с secret, или JWT). Сверяйте timestamp, nonce и replay‑защиту.
SLA приема: отвечайте 200 OK за ≤2–3 c. Тяжелую бизнес‑логику переводите в очередь.
Ретраи: придерживайтесь idempotency на своем endpoint; повторная доставка часто экспоненциальная.
Fallback: периодическая сверка статусов по API при сбоях webhooks.

Пример верификации подписи (псевдокод):

computed = HMAC_SHA256(secret, body + "|" + timestamp)
if header_signature != computed or isExpired(timestamp): reject

Примеры запросов и ответов

Создание платежа (generic пример):

curl -X POST https://api.provider.example/v1/payments \
  -H 'Authorization: Bearer <secret>' \
  -H 'Idempotency-Key: 5f2c-...-a1' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": {"value": 1990.00, "currency": "RUB"},
    "description": "Заказ #A1025",
    "customer": {"email": "[email protected]"},
    "confirmation": {"type": "redirect", "return_url": "https://shop.example/success"},
    "metadata": {"order_id": "A1025"}
  }'

Ответ (сокращенно):

{
  "id": "pay_123",
  "status": "pending",
  "confirmation": {"type": "redirect", "url": "https://pay.example/confirm/abc"}
}

Частичный возврат:

curl -X POST https://api.provider.example/v1/refunds \
  -H 'Authorization: Bearer <secret>' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment_id": "pay_123",
    "amount": {"value": 500.00, "currency": "RUB"},
    "reason": "Частичный возврат по позиции 2"
  }'

Важно: реальные параметры (например, поля для 3‑DS 2.2, device fingerprint, challenge) зависят от провайдера.

Т‑Банк и Альфа‑Банк: особенности API

Запросы вроде «т банк api интернет эквайринг», «тбанк интернет эквайринг документация» и «альфа банк интернет эквайринг api» ведут к официальным порталам разработчиков. Ниже — обобщенная витрина возможностей, сверяйте актуальность в первоисточниках и на наших страницах про банки.

Критерий	Т‑Банк (Tinkoff)	Альфа‑Банк
Типы интеграции	HPP/виджет, server‑to‑server	HPP/виджет, server‑to‑server
Webhooks	Да (подпись HMAC/JWT)	Да (подпись/сертификаты)
Подписки/токены	Часто поддерживаются	Часто поддерживаются
СБП/QR	Поддержка по отдельному API/методам	Поддержка по отдельному API/методам
Тестовый стенд	Sandbox, тест‑карты	Sandbox, тест‑карты
Фискализация	Интеграция через API/партнеров	Интеграция через API/партнеров
SDK/пример	Java/Kotlin/JS/PHP примеры	Java/.NET/JS/PHP примеры

Подробности и актуальные условия смотрите на наших страницах: Т‑Банк: интернет‑эквайринг и Альфа‑Банк: интернет‑эквайринг. Для выбора по стоимости и возможностям — сравнение тарифов банков.

CMS/1C/мобильные приложения

API‑интеграция не исключает готовые модули и плагины — часто это самый быстрый способ вывести MVP, а затем доработать под себя.

1C/ERP: готовые коннекторы и обмен статуса — интеграция 1С и эквайринга.
CMS/конструкторы: Bitrix, Tilda и другие.
Mobile SDK: сценарии в приложении, SCA/3‑DS — см. мобильный интернет‑эквайринг.

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

Лучшие практики и частые ошибки

Idempotency на все «денежные» операции: один order_id = один ключ. Повторный POST не должен создавать новый платеж.
Таймауты и ретраи: 5–10 c таймаут, до 3 повторов с backoff. Следите за 409/429/5xx.
Обработка дубликатов webhooks: проверяйте event_id и храните его в базе.
Сверка подписей и часов: защита от replay‑атак. Синхронизация времени NTP.
Валюта и точность: храните суммы в минорных единицах (копейках) как integer, чтобы избежать ошибок округления.
Налоги и чеки: корректные ставки НДС, предмет расчета, признак способа оплаты — см. онлайн‑касса.
PSD2/SCA‑подобные практики: будьте готовы к флоу браузерных редиректов/3‑DS challenge.
Блок фрод‑рисков: velocity‑лимиты, device‑fingerprint, 3‑DS routing, правила чарджбеков (см. правила и требования).

Тестирование, запуск и контроль

Песочница: карточки‑симуляторы, коды отклонений — тестовый стенд и песочница.
Набор кейсов: успешный платеж, отмена, частичный возврат, повторное уведомление, сбой фискализации — инструкция и примеры.
Прод: включите алерты по росту отказов, времени ответа шлюза, сбоям webhooks.
Бизнес‑контроль: отчеты и акты для учета и налогов, сверки с банком.
Масштабирование: горизонтальные воркеры для обработки уведомлений, очереди, dead‑letter.

Если только начинаете, пройдите гайд: подключение интернет‑эквайринга. Для ИП/ООО/самозанятых есть отдельные рекомендации: эквайринг для ИП, для ООО, для самозанятых.

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

API интернет‑эквайринга дает полный контроль над платежами: кастомный checkout, подписки, автоматические возвраты и глубинную аналитику. Выберите банк/провайдера, разверните песочницу, реализуйте создание платежей и прием webhooks, подключите фискализацию и выведите решение в прод. Готовы к старту? Перейдите к шагам из раздела подключение интернет‑эквайринга и сопоставьте условия по тарифам и комиссиям. Мы поможем выбрать провайдера и спланировать интеграцию под вашу архитектуру.

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